/ Hex Artifact Content
Login

Artifact 3926f5d7422ce8e0641f4fc941fc368c19ef6c94:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 35 38 20 32 30 30 37 2f  in,v 1.258 2007/
05f0: 30 39 2f 30 34 20 31 32 3a 31 38 3a 34 32 20 64  09/04 12:18:42 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f  extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74  *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65  hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a  header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
0840: 2a 0a 2a 2a 20 54 68 65 20 76 65 72 73 69 6f 6e  *.** The version
0850: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
0860: 69 62 72 61 72 79 20 69 73 20 63 6f 6e 74 61 69  ibrary is contai
0870: 6e 65 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  ned in the sqlit
0880: 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 72 20 66  e3.h.** header f
0890: 69 6c 65 20 69 6e 20 61 20 23 64 65 66 69 6e 65  ile in a #define
08a0: 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 56 45   named SQLITE_VE
08b0: 52 53 49 4f 4e 2e 20 20 54 68 65 20 53 51 4c 49  RSION.  The SQLI
08c0: 54 45 5f 56 45 52 53 49 4f 4e 0a 2a 2a 20 6d 61  TE_VERSION.** ma
08d0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
08e0: 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  a string constan
08f0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 72  t..**.** The for
0900: 6d 61 74 20 6f 66 20 74 68 65 20 76 65 72 73 69  mat of the versi
0910: 6f 6e 20 73 74 72 69 6e 67 20 69 73 20 22 58 2e  on string is "X.
0920: 59 2e 5a 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58  Y.Z", where.** X
0930: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0940: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20  rsion number, Y 
0950: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0960: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0970: 5a 0a 2a 2a 20 69 73 20 74 68 65 20 72 65 6c 65  Z.** is the rele
0980: 61 73 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ase number.  The
0990: 20 58 2e 59 2e 5a 20 6d 69 67 68 74 20 62 65 20   X.Y.Z might be 
09a0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22 61 6c 70  followed by "alp
09b0: 68 61 22 20 6f 72 20 22 62 65 74 61 22 2e 0a 2a  ha" or "beta"..*
09c0: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 20 22 33  * For example "3
09d0: 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a  .1.1beta"..**.**
09e0: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20   The X value is 
09f0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0a00: 74 65 2e 20 20 54 68 65 20 58 20 76 61 6c 75 65  te.  The X value
0a10: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68   only changes wh
0a20: 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  en.** backwards 
0a30: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0a40: 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69   broken and we i
0a50: 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62  ntend to never b
0a60: 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61 72 64  reak.** backward
0a70: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0a80: 20 20 54 68 65 20 59 20 76 61 6c 75 65 20 6f 6e    The Y value on
0a90: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a  ly changes when.
0aa0: 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61 6a  ** there are maj
0ab0: 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61 6e  or feature enhan
0ac0: 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  cements that are
0ad0: 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 74   forwards compat
0ae0: 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ible.** but not 
0af0: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0b00: 69 62 6c 65 2e 20 20 54 68 65 20 5a 20 76 61 6c  ible.  The Z val
0b10: 75 65 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  ue is incremente
0b20: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0b30: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0b40: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0b50: 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65   Y is incremente
0b60: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
0b70: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0b80: 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ER is an integer
0b90: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0ba0: 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30 30 20 2b  .** (X*1000000 +
0bb0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f   Y*1000 + Z). Fo
0bc0: 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76  r example, for v
0bd0: 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 62 65 74  ersion "3.1.1bet
0be0: 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 56  a", .** SQLITE_V
0bf0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73  ERSION_NUMBER is
0c00: 20 73 65 74 20 74 6f 20 33 30 30 31 30 30 31 2e   set to 3001001.
0c10: 20 54 6f 20 64 65 74 65 63 74 20 69 66 20 74 68   To detect if th
0c20: 65 79 20 61 72 65 20 75 73 69 6e 67 20 0a 2a 2a  ey are using .**
0c30: 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e 31 20 6f   version 3.1.1 o
0c40: 72 20 67 72 65 61 74 65 72 20 61 74 20 63 6f 6d  r greater at com
0c50: 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 6f 67 72  pile time, progr
0c60: 61 6d 73 20 6d 61 79 20 75 73 65 20 74 68 65 20  ams may use the 
0c70: 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c 49 54 45  test .** (SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e  _VERSION_NUMBER>
0c90: 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a 2a  =3001001)..**.**
0ca0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
0cb0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
0cc0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c  ] and [sqlite3_l
0cd0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
0ce0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
0cf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
0d00: 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d         "--VERS--
0d10: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
0d20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0d30: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d40: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0d50: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0d60: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0d70: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  bers.**.** These
0d80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
0d90: 20 76 61 6c 75 65 73 20 65 71 75 69 76 61 6c 65   values equivale
0da0: 6e 74 20 74 6f 20 74 68 65 20 68 65 61 64 65 72  nt to the header
0db0: 20 63 6f 6e 73 74 61 6e 74 73 0a 2a 2a 20 5b 53   constants.** [S
0dc0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 61  QLITE_VERSION] a
0dd0: 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  nd [SQLITE_VERSI
0de0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 54 68 65  ON_NUMBER].  The
0df0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
0e00: 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
0e10: 69 6e 65 73 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  ines should only
0e20: 20 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72   be different fr
0e30: 6f 6d 20 74 68 65 20 68 65 61 64 65 72 20 76 61  om the header va
0e40: 6c 75 65 73 0a 2a 2a 20 69 66 20 79 6f 75 20 63  lues.** if you c
0e50: 6f 6d 70 69 6c 65 20 79 6f 75 72 20 70 72 6f 67  ompile your prog
0e60: 72 61 6d 20 75 73 69 6e 67 20 61 6e 20 73 71 6c  ram using an sql
0e70: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 72  ite3.h header fr
0e80: 6f 6d 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e  om a.** differen
0e90: 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  t version of SQL
0ea0: 69 74 65 20 74 68 61 74 20 74 68 65 20 76 65 72  ite that the ver
0eb0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 6c 69 62 72  sion of the libr
0ec0: 61 72 79 20 79 6f 75 0a 2a 2a 20 6c 69 6e 6b 20  ary you.** link 
0ed0: 61 67 61 69 6e 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  against..**.** T
0ee0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
0ef0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
0f00: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
0f10: 65 20 74 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a  e text of the.**
0f20: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0f30: 5d 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 73  ] string.  The s
0f40: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0f50: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
0f60: 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 65 72  urns.** a poiner
0f70: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
0f80: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0f90: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
0fa0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70  function.** is p
0fb0: 72 6f 76 69 64 65 64 20 66 6f 72 20 44 4c 4c 20  rovided for DLL 
0fc0: 75 73 65 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e  users who can on
0fd0: 6c 79 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  ly access functi
0fe0: 6f 6e 73 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63  ons and not.** c
0ff0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1000: 74 68 65 20 44 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  the DLL..*/.SQLI
1010: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
1020: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1030: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1040: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1050: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e  ersion(void);.in
1060: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1070: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1080: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1090: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
10a0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
10b0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
10c0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10d0: 72 65 74 75 72 6e 73 20 54 52 55 45 20 28 6e 6f  returns TRUE (no
10e0: 6e 7a 65 72 6f 29 20 69 66 20 53 51 4c 69 74 65  nzero) if SQLite
10f0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1100: 74 68 0a 2a 2a 20 61 6c 6c 20 6f 66 20 69 74 73  th.** all of its
1110: 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64   mutexes enabled
1120: 20 61 6e 64 20 69 73 20 74 68 75 73 20 74 68 72   and is thus thr
1130: 65 61 64 73 61 66 65 2e 20 20 49 74 20 72 65 74  eadsafe.  It ret
1140: 75 72 6e 73 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  urns.** zero if 
1150: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 62  the particular b
1160: 75 69 6c 64 20 69 73 20 66 6f 72 20 73 69 6e 67  uild is for sing
1170: 6c 65 2d 74 68 72 65 61 64 65 64 20 6f 70 65 72  le-threaded oper
1180: 61 74 69 6f 6e 0a 2a 2a 20 6f 6e 6c 79 2e 0a 2a  ation.** only..*
1190: 2a 0a 2a 2a 20 52 65 61 6c 6c 79 20 61 6c 6c 20  *.** Really all 
11a0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 64 6f 65  this routine doe
11b0: 73 20 69 73 20 72 65 74 75 72 6e 20 74 72 75 65  s is return true
11c0: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
11d0: 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
11e0: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 54 48 52  the -DSQLITE_THR
11f0: 45 41 44 53 41 46 45 3d 31 20 6f 70 74 69 6f 6e  EADSAFE=1 option
1200: 20 61 6e 64 20 66 61 6c 73 65 20 69 66 0a 2a 2a   and false if.**
1210: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 2d   compiled with -
1220: 44 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  DSQLITE_THREADSA
1230: 46 45 3d 30 2e 20 20 49 66 20 53 51 4c 69 74 65  FE=0.  If SQLite
1240: 20 75 73 65 73 20 61 6e 0a 2a 2a 20 61 70 70 6c   uses an.** appl
1250: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1260: 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 2c  mutex subsystem,
1270: 20 6d 61 6c 6c 6f 63 20 73 75 62 73 79 73 74 65   malloc subsyste
1280: 6d 2c 20 63 6f 6c 6c 61 74 69 6e 67 0a 2a 2a 20  m, collating.** 
1290: 73 65 71 75 65 6e 63 65 2c 20 56 46 53 2c 20 53  sequence, VFS, S
12a0: 51 4c 20 66 75 6e 63 74 69 6f 6e 2c 20 70 72 6f  QL function, pro
12b0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 2c 20  gress callback, 
12c0: 63 6f 6d 6d 69 74 20 68 6f 6f 6b 2c 0a 2a 2a 20  commit hook,.** 
12d0: 65 78 74 65 6e 73 69 6f 6e 2c 20 6f 72 20 6f 74  extension, or ot
12e0: 68 65 72 20 61 63 63 65 73 73 6f 72 69 65 73 20  her accessories 
12f0: 61 6e 64 20 74 68 65 73 65 20 61 64 64 2d 6f 6e  and these add-on
1300: 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 74 68 72  s are not.** thr
1310: 65 61 64 73 61 66 65 2c 20 74 68 65 6e 20 63 6c  eadsafe, then cl
1320: 65 61 72 6c 79 20 74 68 65 20 63 6f 6d 62 69 6e  early the combin
1330: 61 74 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 62  ation will not b
1340: 65 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a 20  e threadsafe.** 
1350: 65 69 74 68 65 72 2e 20 20 48 65 6e 63 65 2c 20  either.  Hence, 
1360: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6e 65 76  this routine nev
1370: 65 72 20 72 65 70 6f 72 74 73 20 74 68 61 74 20  er reports that 
1380: 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
1390: 73 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  s guaranteed to 
13a0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2c 20 6f  be threadsafe, o
13b0: 6e 6c 79 20 77 68 65 6e 20 69 74 20 69 73 20 67  nly when it is g
13c0: 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a  uaranteed not.**
13d0: 20 74 6f 20 62 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   to be..**.** Th
13e0: 69 73 20 69 73 20 61 6e 20 65 78 70 65 72 69 6d  is is an experim
13f0: 65 6e 74 61 6c 20 41 50 49 20 61 6e 64 20 6d 61  ental API and ma
1400: 79 20 67 6f 20 61 77 61 79 20 6f 72 20 63 68 61  y go away or cha
1410: 6e 67 65 20 69 6e 20 66 75 74 75 72 65 0a 2a 2a  nge in future.**
1420: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1430: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
1440: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
1450: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
1460: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1470: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61   Handle.**.** Ea
1480: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
1490: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
14a0: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
14b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
14d0: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
14e0: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
14f0: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1500: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1510: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1520: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1530: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1540: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1550: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
1560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1570: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1580: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
1590: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
15a0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
15b0: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
15c0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
15d0: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
15e0: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
15f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1600: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1610: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1620: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1630: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
1640: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
1650: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
1660: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
1670: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1680: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1690: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
16a0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
16b0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
16c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69  **.** Some compi
16d0: 6c 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  lers do not supp
16e0: 6f 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f  ort the "long lo
16f0: 6e 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53  ng" datatype.  S
1700: 6f 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20  o we have.** to 
1710: 64 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63  do compiler-spec
1720: 69 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f  ific typedefs fo
1730: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1740: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1750: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e  egers..**.** Man
1760: 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
1770: 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71  ce functions req
1780: 75 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e  uire a 64-bit in
1790: 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e  teger arguments.
17a0: 0a 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66  .** Those interf
17b0: 61 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65  aces are declare
17c0: 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70  d using this typ
17d0: 65 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  edef..*/.#ifdef 
17e0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
17f0: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
1800: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
1810: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1820: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
1830: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1840: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1850: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
1860: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
1870: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
1880: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
1890: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
18a0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
18b0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
18c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
18d0: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
18e0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
18f0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1900: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
1910: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
1920: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
1930: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
1940: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
1950: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
1960: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
1970: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
1980: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
1990: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
19a0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
19b0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
19c0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
19d0: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
19e0: 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65  g-point.*/.#ifde
19f0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
1a00: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
1a10: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
1a20: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
1a30: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1a40: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
1a50: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1a60: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73  .**.** Call this
1a70: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
1a80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
1a90: 72 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73  ructure that was
1aa0: 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72   previously.** r
1ab0: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
1ac0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1ad0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ae0: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
1af0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
1b00: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
1b10: 6e 67 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ng database will
1b20: 20 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a   by.** closed..*
1b30: 2a 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61  *.** All SQL sta
1b40: 74 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64  tements prepared
1b50: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b60: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1b70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1b80: 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73  pare16_v2()] mus
1b90: 74 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75  t be destroyed u
1ba0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1bb0: 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66  nalize()].** bef
1bc0: 6f 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ore this routine
1bd0: 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65   is called. Othe
1be0: 72 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55  rwise, SQLITE_BU
1bf0: 53 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  SY is returned a
1c00: 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
1c10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65  se connection re
1c20: 6d 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  mains open..**.*
1c30: 2a 20 50 61 73 73 69 6e 67 20 74 68 69 73 20 72  * Passing this r
1c40: 6f 75 74 69 6e 65 20 61 20 64 61 74 61 62 61 73  outine a databas
1c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c60: 74 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  t has already be
1c70: 65 6e 0a 2a 2a 20 63 6c 6f 73 65 64 20 72 65 73  en.** closed res
1c80: 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
1c90: 64 20 62 65 68 61 76 69 6f 72 2e 20 20 49 66 20  d behavior.  If 
1ca0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
1cb0: 20 74 68 61 74 0a 2a 2a 20 72 65 66 65 72 65 6e   that.** referen
1cc0: 63 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  ce the same data
1cd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ce0: 61 72 65 20 70 65 6e 64 69 6e 67 20 28 65 69 74  are pending (eit
1cf0: 68 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 73 61  her in the.** sa
1d00: 6d 65 20 74 68 72 65 61 64 20 6f 72 20 69 6e 20  me thread or in 
1d10: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
1d20: 73 29 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  s) when this rou
1d30: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 0a  tine is called,.
1d40: 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d50: 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d60: 64 20 61 6e 64 20 69 73 20 61 6c 6d 6f 73 74 20  d and is almost 
1d70: 63 65 72 74 61 69 6e 6c 79 20 75 6e 64 65 73 69  certainly undesi
1d80: 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  rable..*/.int sq
1d90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
1da0: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
1db0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
1dc0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
1dd0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
1de0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
1df0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
1e00: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
1e10: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
1e20: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
1e30: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
1e40: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
1e50: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
1e60: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
1e70: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
1e80: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
1e90: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
1ea0: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a  n Interface.**.*
1eb0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1ec0: 20 69 73 20 75 73 65 64 20 74 6f 20 64 6f 20 61   is used to do a
1ed0: 20 6f 6e 65 2d 74 69 6d 65 20 65 76 61 6c 75 61   one-time evalua
1ee0: 74 61 74 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a  tation of zero.*
1ef0: 2a 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74  * or more SQL st
1f00: 61 74 65 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38  atements.  UTF-8
1f10: 20 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c   text of the SQL
1f20: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a   statements to.*
1f30: 2a 20 62 65 20 65 76 61 6c 75 74 65 64 20 69 73  * be evaluted is
1f40: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
1f50: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f60: 65 72 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  er.  The stateme
1f70: 6e 74 73 0a 2a 2a 20 61 72 65 20 70 72 65 70 61  nts.** are prepa
1f80: 72 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75  red one by one u
1f90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1fa0: 65 70 61 72 65 28 29 5d 2c 20 65 76 61 6c 75 61  epare()], evalua
1fb0: 74 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ted.** using [sq
1fc0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 74  lite3_step()], t
1fd0: 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
1fe0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1ff0: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
2000: 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  If one or more o
2010: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2020: 65 6e 74 73 20 61 72 65 20 71 75 65 72 69 65 73  ents are queries
2030: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61  , then.** the ca
2040: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2050: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2060: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2070: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  s.** invoked onc
2080: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2090: 66 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75  f the query resu
20a0: 6c 74 2e 20 20 54 68 69 73 20 63 61 6c 6c 62 61  lt.  This callba
20b0: 63 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72  ck.** should nor
20c0: 6d 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20  mally return 0. 
20d0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
20e0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
20f0: 65 72 6f 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65  ero.** value the
2100: 6e 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61  n the query is a
2110: 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73  borted, all subs
2120: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
2130: 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69  ments.** are ski
2140: 70 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c  pped and the sql
2150: 69 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63  ite3_exec() func
2160: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
2170: 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
2180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  .**.** The 4th p
2190: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 69 73  arameter to this
21a0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 6e   interface is an
21b0: 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
21c0: 65 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 61  er that is.** pa
21d0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
21e0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
21f0: 63 74 69 6f 6e 20 61 73 20 69 74 73 20 66 69 72  ction as its fir
2200: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
2210: 0a 2a 2a 20 54 68 65 20 32 6e 64 20 70 61 72 61  .** The 2nd para
2220: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2230: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
2240: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
2250: 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  ** columns in th
2260: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e 20  e query result. 
2270: 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
2280: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
2290: 63 6b 0a 2a 2a 20 69 73 20 61 6e 20 61 72 72 61  ck.** is an arra
22a0: 79 20 6f 66 20 73 74 72 69 6e 67 73 20 68 6f 6c  y of strings hol
22b0: 64 69 6e 67 20 74 68 65 20 76 61 6c 75 65 73 20  ding the values 
22c0: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 0a  for each column.
22d0: 2a 2a 20 61 73 20 65 78 74 72 61 63 74 65 64 20  ** as extracted 
22e0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
22f0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
2300: 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2310: 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2320: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
2330: 6f 66 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 62  of strings.** ob
2340: 74 61 69 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  tained using [sq
2350: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2360: 65 28 29 5d 20 61 6e 64 20 68 6f 6c 64 69 6e 67  e()] and holding
2370: 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  .** the names of
2380: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   each column..**
2390: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
23a0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
23b0: 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72 20   NULL, even for 
23c0: 71 75 65 72 69 65 73 2e 20 20 41 20 4e 55 4c 4c  queries.  A NULL
23d0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
23e0: 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  not an error.  I
23f0: 74 20 6a 75 73 74 20 6d 65 61 6e 73 20 74 68 61  t just means tha
2400: 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  t no callback.**
2410: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
2420: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72  ..**.** If an er
2430: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
2440: 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c   parsing or eval
2450: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 28  uating the SQL (
2460: 62 75 74 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c 65  but.** not while
2470: 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20 63   executing the c
2480: 61 6c 6c 62 61 63 6b 29 20 74 68 65 6e 20 61 6e  allback) then an
2490: 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
24a0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
24b0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
24c0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
24d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
24e0: 6f 63 28 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72  oc()] and.** *er
24f0: 72 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f 20  rmsg is made to 
2500: 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d 65  point to that me
2510: 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c  ssage.  The call
2520: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
2530: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2540: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
2550: 65 6d 6f 72 79 20 75 73 69 6e 67 20 5b 73 71 6c  emory using [sql
2560: 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2570: 20 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c   If errmsg==NULL
2580: 2c 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f 72 20  , then no error 
2590: 6d 65 73 73 61 67 65 20 69 73 20 65 76 65 72 20  message is ever 
25a0: 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  written..**.** T
25b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
25c0: 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20  is is SQLITE_OK 
25d0: 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
25e0: 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 73 6f  errors and.** so
25f0: 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  me other [SQLITE
2600: 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  _OK | return cod
2610: 65 5d 20 69 66 20 74 68 65 72 65 20 69 73 20 61  e] if there is a
2620: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 54 68  n error.  .** Th
2630: 65 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 74  e particular ret
2640: 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65 6e 64  urn value depend
2650: 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20 6f 66  s on the type of
2660: 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69   error. .**.*/.i
2670: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
2680: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
2690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26b0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
26c0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26d0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
26e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
2700: 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74  valuted */.  int
2710: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
2720: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
2730: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
2740: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
2750: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
2760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2770: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2780: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
2790: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
27a0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
27b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
27d0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
27e0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
27f0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2800: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
2810: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  DS: SQLITE_OK.**
2820: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
2830: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2840: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
2850: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
2860: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61 62   set shown.** ab
2870: 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ove in order to 
2880: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
2890: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
28a0: 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74 20 63  .** The result c
28b0: 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 20 74  odes above are t
28c0: 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74  he only ones ret
28d0: 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
28e0: 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 75 6c  in its.** defaul
28f0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e  t configuration.
2900: 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 5b    However, the [
2910: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2920: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
2930: 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65 20 75  .** API can be u
2940: 73 65 64 20 74 6f 20 73 65 74 20 61 20 64 61 74  sed to set a dat
2950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f 69 6e  abase connectoin
2960: 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72 65 20   to return more 
2970: 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65 73 75  detailed.** resu
2980: 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  lt codes..**.** 
2990: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
29a0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
29b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29c0: 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66  odes].**.*/.#def
29d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
29e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
29f0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
2a00: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
2a10: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
2a20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2a30: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
2a40: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
2a50: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
2a60: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
2a70: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
2a80: 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53     2   /* NOT US
2a90: 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67  ED. Internal log
2aa0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
2ab0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
2ac0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
2ad0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
2ae0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
2af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2b00: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
2b10: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
2b20: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
2b30: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
2b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
2b50: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
2b60: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
2b70: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
2b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b90: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
2ba0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
2bb0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
2bc0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
2bd0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
2be0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
2bf0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
2c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c10: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
2c20: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
2c30: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
2c40: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
2c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
2c60: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
2c70: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
2c80: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
2c90: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
2ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
2cb0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
2cc0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
2cd0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
2ce0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
2cf0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
2d00: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
2d10: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
2d20: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
2d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d40: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
2d50: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
2d60: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
2d70: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
2d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
2d90: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
2da0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
2db0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
2dc0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
2dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
2de0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
2df0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
2e00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2e10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2e20: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
2e30: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
2e40: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
2e50: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
2e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e70: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
2e80: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
2e90: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
2ea0: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
2eb0: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
2ec0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2ed0: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
2ee0: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
2ef0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
2f00: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
2f10: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
2f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
2f40: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
2f50: 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f  to contraint vio
2f60: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
2f70: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
2f80: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
2f90: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
2fa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2fb0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
2fc0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
2fd0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
2fe0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ff0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
3000: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
3010: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
3020: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
3030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
3040: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
3050: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
3060: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
3070: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
3080: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
3090: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
30a0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
30b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
30c0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
30d0: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
30e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
30f0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
3100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3110: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
3120: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
3130: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
3140: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
3150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
3160: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
3170: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
3180: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
3190: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
31a0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
31b0: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
31c0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
31d0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
31e0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
31f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
3200: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3210: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
3220: 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  Codes.**.** In i
3230: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
3240: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
3250: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
3260: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
3270: 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c 74  nteger.** result
3280: 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 65 64   codes described
3290: 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 65 73   at result-codes
32a0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
32b0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
32c0: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
32d0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
32e0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
32f0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
3300: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
3310: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
3320: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
3330: 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73 20  oblems as users 
3340: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
3350: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
3360: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
3370: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
3380: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
3390: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
33a0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
33b0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
33c0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
33d0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
33e0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
33f0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
3400: 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 78 74  errors.  The ext
3410: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3420: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 28  es are enabled (
3430: 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 6f 72  or disabled) for
3440: 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61   .** each databa
3450: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
3460: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
3470: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
3480: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
3490: 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66  ..** .** Some of
34a0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65   the available e
34b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
34c0: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20  odes are listed 
34d0: 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78 70  above..** We exp
34e0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
34f0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
3500: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
3510: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
3520: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
3530: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
3540: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
3550: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
3560: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
3570: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
3580: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
3590: 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  Lite..** .** The
35a0: 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66   symbolic name f
35b0: 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  or an extended r
35c0: 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79  esult code alway
35d0: 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 65 6c  s contains a rel
35e0: 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79 20  ated.** primary 
35f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61  result code as a
3600: 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d 61 72   prefix.  Primar
3610: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63  y result codes c
3620: 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 0a  ontain a single.
3630: 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  ** "_" character
3640: 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 75  .  Extended resu
3650: 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e  lt codes contain
3660: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22   two or more "_"
3670: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
3680: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  The numeric valu
3690: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64  e of an extended
36a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61 6e   result code can
36b0: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
36c0: 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   its.** correspo
36d0: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
36e0: 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61 73  sult code by mas
36f0: 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f 77  king off the low
3700: 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  er 8 bytes..**.*
3710: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
3720: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
3730: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
3740: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
3750: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
3760: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
3770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3780: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53  READ          (S
3790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
37a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
37b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
37c0: 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45  _READ    (SQLITE
37d0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
37e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37f0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
3800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3810: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
3820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3830: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
3840: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3850: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
3860: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
3870: 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54  FSYNC     (SQLIT
3880: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
3890: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
38a0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
38b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
38c0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
38d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
38e0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
38f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3900: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
3910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
3920: 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  OCK        (SQLI
3930: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
3940: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3950: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
3960: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3970: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
3980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3990: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
39a0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
39b0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
39c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
39d0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51  LOCKED       (SQ
39e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
39f0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
3a00: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
3a10: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
3a20: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f 6d 62  tions.**.** Comb
3a30: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
3a40: 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76 61 6c  ollowing bit val
3a50: 75 65 73 20 61 72 65 20 75 73 65 64 20 61 73 20  ues are used as 
3a60: 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  the.** third arg
3a70: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
3a80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3a90: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
3aa0: 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72 67 75  * as fourth argu
3ab0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f 70 65  ment to the xOpe
3ac0: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
3ad0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
3ae0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f 0a 23   object..**.*/.#
3af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b00: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
3b10: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
3b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b30: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
3b40: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
3b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b60: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
3b70: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
3b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3b90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
3ba0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
3bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3bc0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
3bd0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
3be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3bf0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
3c00: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
3c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c20: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
3c30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
3c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c50: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
3c60: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3c80: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
3c90: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23      0x00000800.#
3ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3cb0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
3cc0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
3cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3ce0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
3cf0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
3d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3d10: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
3d20: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a  L   0x00004000..
3d30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3d40: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
3d50: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
3d60: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
3d70: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
3d80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
3d90: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
3da0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
3db0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
3dc0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 66 6f  vector of the fo
3dd0: 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74 20 76  llowing.** bit v
3de0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
3df0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
3e00: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
3e10: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
3e20: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
3e30: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
3e40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
3e50: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
3e60: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
3e70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e80: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
3e90: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
3ea0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
3eb0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3ec0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
3ed0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
3ee0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
3ef0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
3f00: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
3f10: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
3f20: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
3f30: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
3f40: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
3f50: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
3f60: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3f70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
3f80: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
3f90: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
3fa0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
3fb0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
3fc0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
3fd0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
3fe0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
3ff0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
4000: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
4010: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
4020: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
4030: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
4040: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
4050: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
4060: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
4070: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
4080: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
4090: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
40a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
40c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
40d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
40e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
40f0: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  2       0x000000
4100: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
4120: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4130: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
4140: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
4150: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4160: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
4170: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
4180: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4190: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
41a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
41b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
41c0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
41d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
41e0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
41f0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
4200: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
4210: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
4220: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
4230: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
4240: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31  K       0x000001
4250: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4260: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4270: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32  END     0x000002
4280: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4290: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
42a0: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34  AL      0x000004
42b0: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
42c0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
42d0: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
42e0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
42f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
4300: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
4310: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
4320: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
4330: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
4340: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
4350: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
4360: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
4370: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4380: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
4390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
43a0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
43b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
43c0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
43d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
43e0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
43f0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
4400: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
4410: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
4420: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
4430: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
4440: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
4450: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
4460: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
4470: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
4480: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
4490: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
44a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
44b0: 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  ** object it use
44c0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
44d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
44e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
44f0: 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  as.** the second
4500: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
4510: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
4520: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
4530: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
4540: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
4550: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
4560: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
4570: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
4580: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
4590: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
45a0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
45b0: 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  shed.  The SQLIT
45c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65  E_SYNC_NORMAL me
45d0: 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e  ans .** to use n
45e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
45f0: 6d 61 6e 74 69 63 73 2e 20 20 54 68 65 20 53 51  mantics.  The SQ
4600: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
4610: 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f  lag means .** to
4620: 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74   use Mac OS-X st
4630: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
4640: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
4650: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4660: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
4670: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
4680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
4690: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
46a0: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
46b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
46c0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
46d0: 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  0.../*.** CAPI3R
46e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
46f0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
4700: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
4710: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
4720: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
4730: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
4740: 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  OS.** interface 
4750: 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75  layer.  Individu
4760: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  al OS interface 
4770: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
4780: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
4790: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
47a0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
47b0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
47c0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
47d0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
47e0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
47f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
4800: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
4810: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
4820: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
4830: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
4840: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
4850: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
4860: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
4870: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
4880: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
4890: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
48a0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
48b0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
48c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
48d0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
48e0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
48f0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
4900: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
4910: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
4920: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
4930: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
4940: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
4950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
4960: 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63  ] xOpen method c
4970: 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65  ontains a pointe
4980: 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61  r to.** an insta
4990: 6e 63 65 20 6f 66 20 74 68 65 20 74 68 69 73 20  nce of the this 
49a0: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
49b0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
49c0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64  .** methods used
49d0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
49e0: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ous operations a
49f0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
4a00: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  file..**.** The 
4a10: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
4a20: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
4a30: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
4a40: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
4a50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
4a60: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
4a70: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
4a80: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20  rmal fsync()..* 
4a90: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
4aa0: 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58  ce is an.** OS-X
4ab0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
4ac0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e    The SQLITE_SYN
4ad0: 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20  C_DATA flag may 
4ae0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a  be ORed in to.**
4af0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
4b00: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
4b10: 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74  the file and not
4b20: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
4b30: 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64   to be.** synced
4b40: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74  ..** .** The int
4b50: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
4b60: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
4b70: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
4b80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
4b90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
4ba0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
4bb0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
4bc0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
4bd0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
4be0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
4bf0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
4c00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
4c10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
4c20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
4c30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
4c40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
4c50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
4c60: 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20   the lock.  .** 
4c70: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
4c80: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
4c90: 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20  looks.** to see 
4ca0: 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  if any database 
4cb0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68  connection, eith
4cc0: 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72  er in this.** pr
4cd0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
4ce0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
4cf0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45  is holding an RE
4d00: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
4d10: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
4d20: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
4d30: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
4d40: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
4d50: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
4d60: 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a   false if not..*
4d70: 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  * .** The xFileC
4d80: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
4d90: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
4da0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
4db0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
4dc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
4dd0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
4de0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
4df0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
4e00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
4e10: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
4e20: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
4e30: 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  op" argument.** 
4e40: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70  is an integer op
4e50: 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 72  code.   The thir
4e60: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
4e70: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
4e80: 65 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  er which is inte
4e90: 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69  nded to be a poi
4ea0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72  nter.** to a str
4eb0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
4ec0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
4ed0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
4ee0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
4ef0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
4f00: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
4f10: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
4f20: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
4f30: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
4f40: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
4f50: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
4f60: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
4f70: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
4f80: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
4f90: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
4fa0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
4fb0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
4fc0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
4fd0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
4fe0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
4ff0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
5000: 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c  serves opcodes l
5010: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
5020: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a   its own use. .*
5030: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
5040: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
5050: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
5060: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
5070: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
5080: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
5090: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
50a0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
50b0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
50c0: 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74  pcodes .** great
50d0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
50e0: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a  void conflicts..
50f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
5100: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
5110: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
5120: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
5130: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
5140: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
5150: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
5160: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
5170: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
5180: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
5190: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
51a0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
51b0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
51c0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
51d0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
51e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
51f0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
5200: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
5210: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
5220: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
5230: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
5240: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5250: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
5260: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5270: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
5280: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
5290: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
52a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
52b0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
52c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
52d0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
52e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
52f0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
5300: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
5310: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
5320: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5330: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
5340: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5350: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
5360: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5370: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
5380: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
5390: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
53a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
53b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
53c0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
53d0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
53e0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
53f0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5400: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5410: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5420: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5430: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5440: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5450: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5460: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5470: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5480: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5490: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
54a0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
54b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
54c0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
54d0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
54e0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
54f0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5500: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5510: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5520: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5530: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5540: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5550: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5560: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5570: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5580: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5590: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
55a0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
55b0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
55c0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
55d0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
55e0: 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  te()..*/.typedef
55f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
5600: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
5610: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
5620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
5630: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
5640: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
5650: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
5660: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
5670: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
5680: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
5690: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
56a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
56b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
56c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
56d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
56e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
56f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
5700: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
5710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
5720: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
5730: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
5740: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5750: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
5760: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
5770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
5780: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
5790: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
57a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
57b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
57c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
57d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
57e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
57f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
5800: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
5810: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
5820: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5830: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
5840: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
5850: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
5860: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
5870: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
5880: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
5890: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
58a0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
58b0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
58c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
58d0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
58e0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
58f0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
5900: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
5910: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
5920: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
5930: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
5940: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
5950: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
5960: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5970: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
5980: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
5990: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
59a0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
59b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
59c0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
59d0: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
59e0: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
59f0: 6f 70 63 6f 64 65 20 63 61 73 65 73 20 74 68 65  opcode cases the
5a00: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
5a10: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
5a20: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
5a30: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
5a40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
5a50: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
5a60: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
5a70: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
5a80: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
5a90: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
5aa0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
5ab0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
5ac0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
5ad0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
5ae0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
5af0: 74 6f 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  to.  This capabi
5b00: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
5b10: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
5b20: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
5b30: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
5b40: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
5b50: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
5b60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b70: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
5b80: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
5b90: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
5ba0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
5bb0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
5bc0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
5bd0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
5be0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
5bf0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
5c00: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
5c10: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
5c20: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
5c30: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
5c40: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
5c50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
5c60: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
5c70: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
5c80: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
5c90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
5ca0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
5cb0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
5cc0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
5cd0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
5ce0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
5cf0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
5d00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
5d10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5d20: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
5d30: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
5d40: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
5d50: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
5d60: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
5d70: 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  en the.** SQLite
5d80: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
5d90: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
5da0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
5db0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
5dc0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
5dd0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
5de0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
5df0: 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  em"..**.** The i
5e00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
5e10: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
5e20: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 66   may be larger f
5e30: 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76 65 72  or future.** ver
5e40: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
5e50: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
5e60: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
5e70: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
5e80: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
5e90: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
5ea0: 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a   increased..**.*
5eb0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
5ec0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
5ed0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
5ee0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
5ef0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
5f00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
5f10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
5f20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
5f30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
5f40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
5f50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
5f60: 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20 61 72  d vfs modules ar
5f70: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
5f80: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
5f90: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
5fa0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
5fb0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
5fc0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
5fd0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
5fe0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
5ff0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
6000: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
6010: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
6020: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
6030: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
6040: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
6050: 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   list..**.** The
6060: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
6070: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20  the only fields 
6080: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
6090: 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  fs .** structure
60a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
60b0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
60c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
60d0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
60e0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
60f0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
6100: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
6110: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
6120: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
6130: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
6140: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
6150: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
6160: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
6170: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
6180: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
6190: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
61a0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
61b0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
61c0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
61d0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
61e0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
61f0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
6200: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
6210: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
6220: 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67  zFilename string
6230: 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f   passed to.** xO
6240: 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c 6c 20  pen() is a full 
6250: 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65 6e 65  pathname as gene
6260: 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c 50 61  rated by xFullPa
6270: 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20  thname() and.** 
6280: 74 68 61 74 20 74 68 65 20 73 74 72 69 6e 67 20  that the string 
6290: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
62a0: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
62b0: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
62c0: 20 63 61 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65   called.  So the
62d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
62e0: 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  can store a poin
62f0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
6300: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
6310: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
6320: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
6330: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a  some reason..**.
6340: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6350: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
6360: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
6370: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
6380: 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
6390: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 49 66 20  open_v2()].  If 
63a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
63b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
63c0: 6e 31 36 28 29 5d 0a 2a 2a 20 69 73 20 75 73 65  n16()].** is use
63d0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 73  d, then flags is
63e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
63f0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
6400: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
6410: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
6420: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
6430: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
6440: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
6450: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
6460: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
6470: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
6480: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
6490: 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20  y be.** set..** 
64a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
64b0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
64c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
64d0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
64e0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
64f0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
6500: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
6510: 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
6520: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
6530: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
6540: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
6550: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
6560: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
6570: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
6580: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
6590: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
65a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
65b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
65c0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
65d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
65e0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
65f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6600: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
6610: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
6620: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
6630: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
6640: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
6650: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
6660: 68 61 6e 67 65 73 20 74 68 65 20 77 61 79 20 69  hanges the way i
6670: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
6680: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
6690: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
66a0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
66b0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
66c0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
66d0: 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68 74 20 6d  ollback, might m
66e0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
66f0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
6700: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
6710: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
6720: 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73 6f 20 61  al are.** also a
6730: 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20 61 74 74   no-op.  Any att
6740: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
6750: 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75 72 6e 20   journal return 
6760: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 0a 2a 2a  SQLITE_IOERR..**
6770: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
6780: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
6790: 6f 67 6e 69 7a 65 20 74 68 65 20 61 20 64 61 74  ognize the a dat
67a0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 0a  abase file will.
67b0: 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ** be doing page
67c0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
67d0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
67e0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20 6f 72 64   in a random ord
67f0: 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74 20 75 70  er.** and set up
6800: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
6810: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
6820: 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  ** .** SQLite mi
6830: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
6840: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
6850: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
6860: 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a  Open.** method:.
6870: 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ** .** <ul>.** <
6880: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
6890: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
68a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
68b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
68c0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
68d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
68e0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
68f0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
6900: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
6910: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
6920: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 69   is closed.  Thi
6930: 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  s will always be
6940: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 0a 2a   set for TEMP .*
6950: 2a 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  * databases and 
6960: 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72  journals and for
6970: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20 20 54   subjournals.  T
6980: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
6990: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
69a0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
69b0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
69c0: 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ned.** for exclu
69d0: 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68  sive access.  Th
69e0: 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66  is flag is set f
69f0: 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63  or all files exc
6a00: 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ept.** for the m
6a10: 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
6a20: 65 2e 0a 2a 2a 20 0a 2a 2a 20 53 70 61 63 65 20  e..** .** Space 
6a30: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
6a40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
6a50: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
6a60: 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 61 72  the third .** ar
6a70: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 20  gument to xOpen 
6a80: 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  is allocated by 
6a90: 63 61 6c 6c 65 72 20 28 74 68 65 20 53 51 4c 69  caller (the SQLi
6aa0: 74 65 20 63 6f 72 65 29 2e 20 0a 2a 2a 20 73 7a  te core). .** sz
6ab0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 61 72 65  OsFile bytes are
6ac0: 20 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20 74   allocated for t
6ad0: 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  his object.  The
6ae0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 0a 2a 2a   xOpen method.**
6af0: 20 66 69 6c 6c 73 20 69 6e 20 74 68 65 20 61 6c   fills in the al
6b00: 6c 6f 63 61 74 65 64 20 73 70 61 63 65 2e 0a 2a  located space..*
6b10: 2a 20 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  * .** The flags 
6b20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
6b30: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
6b40: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
6b50: 54 53 5d 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20  TS] .** to test 
6b60: 66 6f 72 20 74 68 65 20 65 78 69 73 74 61 6e 63  for the existanc
6b70: 65 20 6f 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20  e of a file,.** 
6b80: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
6b90: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 20  S_READWRITE] to 
6ba0: 74 65 73 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69  test to see.** i
6bb0: 66 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  f a file is read
6bc0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
6bd0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
6be0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
6bf0: 20 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20   test to see if 
6c00: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
6c10: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  st readable.  Th
6c20: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 20  e file can be a 
6c30: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
6c40: 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  * .** SQLite wil
6c50: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
6c60: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
6c70: 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66 6f 72  hname+1 byte for
6c80: 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74 20 62  .** the output b
6c90: 75 66 66 65 72 73 20 66 6f 72 20 78 47 65 74 54  uffers for xGetT
6ca0: 65 6d 70 4e 61 6d 65 20 61 6e 64 20 78 46 75 6c  empName and xFul
6cb0: 6c 50 61 74 68 6e 61 6d 65 2e 0a 2a 2a 20 0a 2a  lPathname..** .*
6cc0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
6cd0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
6ce0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
6cf0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
6d00: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
6d10: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
6d20: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
6d30: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
6d40: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
6d50: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
6d60: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
6d70: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
6d80: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
6d90: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
6da0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
6db0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
6dc0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
6dd0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
6de0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
6df0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
6e00: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
6e10: 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68  ss obtained.  Th
6e20: 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65  e.** xSleep() me
6e30: 74 68 6f 64 20 63 61 75 73 65 20 74 68 65 20 63  thod cause the c
6e40: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
6e50: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
6e60: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
6e70: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
6e80: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
6e90: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
6ea0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
6eb0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
6ec0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
6ed0: 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74  nt date and.** t
6ee0: 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ime..*/.typedef 
6ef0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
6f00: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
6f10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
6f20: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
6f30: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
6f40: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
6f50: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
6f60: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
6f70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
6f80: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
6f90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
6fa0: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
6fb0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
6fc0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
6fd0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
6fe0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
6ff0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
7000: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
7010: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
7020: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
7030: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
7040: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
7050: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
7060: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
7070: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
7080: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
7090: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
70a0: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
70b0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
70c0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
70d0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
70e0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
70f0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
7100: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
7110: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
7120: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7130: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
7140: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
7150: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
7160: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7170: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
7180: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54  );.  int (*xGetT
7190: 65 6d 70 4e 61 6d 65 29 28 73 71 6c 69 74 65 33  empName)(sqlite3
71a0: 5f 76 66 73 2a 2c 20 63 68 61 72 20 2a 7a 4f 75  _vfs*, char *zOu
71b0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
71c0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
71d0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
71e0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 68 61 72  har *zName, char
71f0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
7200: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
7210: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7220: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
7230: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
7240: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
7250: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
7260: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
7270: 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28  void *(*xDlSym)(
7280: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
7290: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
72a0: 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64  zSymbol);.  void
72b0: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
72c0: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
72d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
72e0: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
72f0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
7300: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
7310: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
7320: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
7330: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
7340: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
7350: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
7360: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f  *, double*);.  /
7370: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
7380: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
7390: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
73a0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
73b0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
73c0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
73d0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
73e0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
73f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
7400: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
7410: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
7420: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7430: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
7440: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
7450: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
7460: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
7470: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
7480: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
7490: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
74a0: 20 74 68 65 20 6b 69 6e 64 20 6f 66 20 77 68 61   the kind of wha
74b0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
74c0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
74d0: 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c  s method is.** l
74e0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 57 69 74  ooking for.  Wit
74f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
7500: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
7510: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
7520: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
7530: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
7540: 78 69 73 74 73 2e 20 20 57 69 74 68 20 53 51 4c  xists.  With SQL
7550: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
7560: 52 49 54 45 2c 0a 2a 2a 20 74 68 65 20 78 41 63  RITE,.** the xAc
7570: 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63  cess method chec
7580: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks to see if the
7590: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65   file is both re
75a0: 61 64 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 77 72  adable.** and wr
75b0: 69 74 61 62 6c 65 2e 20 20 57 69 74 68 20 53 51  itable.  With SQ
75c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
75d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
75e0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f  hod.** checks to
75f0: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
7600: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
7610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7620: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
7630: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
7640: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
7650: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
7660: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
7670: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
7680: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
7690: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
76a0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
76b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
76c0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
76d0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53  sables the.** [S
76e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
76f0: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
7700: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
7710: 65 2e 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74  e..** By default
7720: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
7730: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
7740: 20 6f 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65   of only 26 inte
7750: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
7760: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
7770: 5d 2e 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65  ].  When extende
7780: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a  d result codes.*
7790: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  * are enabled by
77a0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
77b0: 68 65 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20  he repetoire of 
77c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e  result codes can
77d0: 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67   be.** much larg
77e0: 65 72 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65  er and can (hope
77f0: 66 75 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d  fully) provide m
7800: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
7810: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
7820: 74 20 74 68 65 20 63 61 75 73 65 20 6f 66 20 61  t the cause of a
7830: 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
7840: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
7850: 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  nt is a boolean 
7860: 76 61 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73  value that turns
7870: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
7880: 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64  .** codes on and
7890: 20 6f 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20   off.  Extended 
78a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
78b0: 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 20   off by default 
78c0: 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  for.** backwards
78d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
78e0: 69 74 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f  ith older versio
78f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
7900: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
7910: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
7920: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
7930: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
7940: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
7950: 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
7960: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
7970: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
7980: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
7990: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
79a0: 65 72 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64  er key.** called
79b0: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
79c0: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
79d0: 73 20 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61  s available as a
79e0: 6e 20 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20  n undeclared.** 
79f0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
7a00: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
7a10: 49 44 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62  ID_.  If the tab
7a20: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
7a30: 6f 66 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47  of.** type INTEG
7a40: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
7a50: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20  hen that column 
7a60: 69 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c  is another an al
7a70: 69 61 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72  ias for the.** r
7a80: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
7a90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
7aa0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
7ab0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
7ac0: 53 45 52 54 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  SERT into.** the
7ad0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
7ae0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
7af0: 65 63 74 69 6f 6e 20 67 69 76 65 6e 20 69 6e 20  ection given in 
7b00: 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 61 72  the first .** ar
7b10: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 69  gument.  If no i
7b20: 6e 73 65 72 74 73 20 68 61 76 65 20 65 76 65 72  nserts have ever
7b30: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69   occurred on thi
7b40: 73 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  s database.** co
7b50: 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
7b60: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
7b70: 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f  * If an INSERT o
7b80: 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
7b90: 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65  rigger, then the
7ba0: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a   rowid of the.**
7bb0: 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73   inserted row is
7bc0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
7bd0: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
7be0: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
7bf0: 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  .** is running. 
7c00: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
7c10: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
7c20: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
7c30: 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  rned.** by this 
7c40: 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
7c50: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
7c60: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
7c70: 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72  e the.** trigger
7c80: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66   fired..**.** If
7c90: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
7ca0: 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72  does a new inser
7cb0: 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
7cc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7cd0: 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20  n.** while this 
7ce0: 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
7cf0: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
7d00: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
7d10: 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68  ert rowid,.** th
7d20: 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
7d30: 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
7d40: 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
7d50: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
7d60: 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
7d70: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
7d80: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
7d90: 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
7da0: 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
7db0: 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
7dc0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
7dd0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
7de0: 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
7df0: 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
7e00: 6e 67 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65  nged.** (or inse
7e10: 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29  rted or deleted)
7e20: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
7e30: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
7e40: 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e  t.  Only.** chan
7e50: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
7e60: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
7e70: 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
7e80: 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c  PDATE, or.** DEL
7e90: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
7ea0: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
7eb0: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
7ec0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
7ed0: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ers are not coun
7ee0: 74 65 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73  ted.  Use the [s
7ef0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
7f00: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
7f10: 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
7f20: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
7f30: 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e  changes includin
7f40: 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
7f50: 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a   by triggers..**
7f60: 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62  .** Within the b
7f70: 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
7f80: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  , the sqlite3_ch
7f90: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
7fa0: 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c  e can be.** call
7fb0: 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
7fc0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
7fd0: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
7fe0: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
7ff0: 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
8000: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
8010: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
8020: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
8030: 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
8040: 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20  All changes are 
8050: 63 6f 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66  counted, even if
8060: 20 74 68 65 79 20 77 65 72 65 20 6c 61 74 65 72   they were later
8070: 20 75 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20   undone by a.** 
8080: 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52  ROLLBACK or ABOR
8090: 54 2e 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e  T.  Except, chan
80a0: 67 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  ges associated w
80b0: 69 74 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64  ith creating and
80c0: 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62  .** dropping tab
80d0: 6c 65 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  les are not coun
80e0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ted..**.** If a 
80f0: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73  callback invokes
8100: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
8110: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
8120: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
8130: 79 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  y,.** then the c
8140: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e  hanges in the in
8150: 6e 65 72 2c 20 72 65 63 75 72 73 69 76 65 20 63  ner, recursive c
8160: 61 6c 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20  all are counted 
8170: 74 6f 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68  together.** with
8180: 20 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20   the changes in 
8190: 74 68 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a  the outer call..
81a0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
81b0: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
81c0: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
81d0: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
81e0: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
81f0: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
8200: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
8210: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
8220: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
8230: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
8240: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
8250: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
8260: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
8270: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
8280: 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69  f.** this optimi
8290: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e  zation, the chan
82a0: 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45  ge count for "DE
82b0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
82c0: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f   will be.** zero
82d0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
82e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
82f0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
8300: 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
8310: 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67  e.** table. To g
8320: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
8330: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
8340: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
8350: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
8360: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
8370: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
8380: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
8390: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
83a0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
83b0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
83c0: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74  ction.** while t
83d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
83e0: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
83f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
8400: 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
8410: 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
8420: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
8430: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
8440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8450: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
8460: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
8470: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
8480: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
8490: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
84a0: 73 65 20 72 6f 77 73 20 74 68 61 74 20 68 61 76  se rows that hav
84b0: 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69  e been.** modifi
84c0: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
84d0: 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
84e0: 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
84f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  the database han
8500: 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65  dle.** was opene
8510: 64 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  d. This includes
8520: 20 55 50 44 41 54 45 2c 20 49 4e 53 45 52 54 20   UPDATE, INSERT 
8530: 61 6e 64 20 44 45 4c 45 54 45 20 73 74 61 74 65  and DELETE state
8540: 6d 65 6e 74 73 20 65 78 65 63 75 74 65 64 0a 2a  ments executed.*
8550: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 74 72 69  * as part of tri
8560: 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 41  gger programs. A
8570: 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  ll changes are c
8580: 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  ounted as soon a
8590: 73 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  s the.** stateme
85a0: 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
85b0: 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
85c0: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
85d0: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a  ent handle is.**
85e0: 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
85f0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
8600: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
8610: 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
8620: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
8630: 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74  e3_change()] int
8640: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51  erface..**.** SQ
8650: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
8660: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
8670: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
8680: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
8690: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
86a0: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
86b0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
86c0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
86d0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
86e0: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
86f0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
8700: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72  ual elements for
8710: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
8720: 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69  ecause of.** thi
8730: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
8740: 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74  the change count
8750: 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f   for "DELETE FRO
8760: 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65  M table" will be
8770: 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c  .** zero regardl
8780: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
8790: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
87a0: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
87b0: 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62  ly in the.** tab
87c0: 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63  le. To get an ac
87d0: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
87e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
87f0: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
8800: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
8810: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
8820: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nstead..**.** If
8830: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
8840: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
8850: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
8860: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
8870: 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
8880: 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ine is running t
8890: 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
88a0: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
88b0: 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  tine.** is undef
88c0: 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
88d0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
88e0: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
88f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
8900: 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
8910: 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
8920: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
8930: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
8940: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
8950: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
8960: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
8970: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
8980: 70 70 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69  pportunity.  Thi
8990: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
89a0: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
89b0: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
89c0: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
89d0: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
89e0: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
89f0: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
8a00: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
8a10: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
8a20: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
8a30: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
8a40: 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
8a50: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
8a60: 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
8a70: 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
8a80: 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
8a90: 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
8aa0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8ab0: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
8ac0: 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
8ad0: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
8ae0: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64  routine with a d
8af0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8b00: 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  on that.** is cl
8b10: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
8b20: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
8b30: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
8b40: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
8b50: 65 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  e SQL operation 
8b60: 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
8b70: 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
8b80: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
8b90: 54 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  T]..** If an int
8ba0: 65 72 72 75 70 74 65 64 20 6f 70 65 72 61 74 69  errupted operati
8bb0: 6f 6e 20 77 61 73 20 61 6e 20 75 70 64 61 74 65  on was an update
8bc0: 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
8bd0: 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
8be0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
8bf0: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
8c00: 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  saction will be 
8c10: 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61  rolled.** back a
8c20: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f  utomatically..*/
8c30: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
8c40: 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
8c50: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8c60: 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
8c70: 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
8c80: 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
8c90: 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
8ca0: 6f 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 20  ons return true 
8cb0: 69 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70  if the given inp
8cc0: 75 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69  ut string compri
8cd0: 73 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ses.** one or mo
8ce0: 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20  re complete SQL 
8cf0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20  statements. For 
8d00: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  the sqlite3_comp
8d10: 6c 65 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20  lete() call,.** 
8d20: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75  the parameter mu
8d30: 73 74 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d  st be a nul-term
8d40: 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
8d50: 69 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69  ing. For.** sqli
8d60: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
8d70: 2c 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  , a nul-terminat
8d80: 65 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20  ed machine byte 
8d90: 6f 72 64 65 72 20 55 54 46 2d 31 36 20 73 74 72  order UTF-16 str
8da0: 69 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72  ing.** is requir
8db0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
8dc0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
8dd0: 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
8de0: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
8df0: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
8e00: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
8e10: 72 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f  red text forms o
8e20: 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c  ne or more compl
8e30: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
8e40: 74 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  ts or.** if addi
8e50: 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
8e60: 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
8e70: 6e 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d  nding the statem
8e80: 65 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  ents into.** SQL
8e90: 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
8ea0: 20 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69   The algorithm i
8eb0: 73 20 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68  s simple.  If th
8ec0: 65 20 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e  e .** last token
8ed0: 20 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 63   other than spac
8ee0: 65 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  es and comments 
8ef0: 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20  is a semicolon, 
8f00: 74 68 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20  then return .** 
8f10: 74 72 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c  true.  Actually,
8f20: 20 74 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69   the algorithm i
8f30: 73 20 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20  s a little more 
8f40: 63 6f 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e  complicated than
8f50: 20 74 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65   that.** in orde
8f60: 72 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74  r to deal with t
8f70: 72 69 67 67 65 72 73 2c 20 62 75 74 20 74 68 65  riggers, but the
8f80: 20 62 61 73 69 63 20 69 64 65 61 20 69 73 20 74   basic idea is t
8f90: 68 65 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a  he same:  the.**
8fa0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
8fb0: 74 20 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73  t complete unles
8fc0: 73 20 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73  s it ends in a s
8fd0: 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74  emicolon..*/.int
8fe0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
8ff0: 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
9000: 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
9010: 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
9020: 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
9030: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
9040: 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
9050: 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
9060: 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
9070: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
9080: 65 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63  e identifies a c
9090: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
90a0: 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
90b0: 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76  nvoked.** whenev
90c0: 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  er an attempt is
90d0: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
90e0: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a  database table .
90f0: 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  ** that another 
9100: 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73  thread or proces
9110: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
9120: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
9130: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
9140: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
9150: 5d 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d  ].** (or sometim
9160: 65 73 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  es [SQLITE_IOERR
9170: 5f 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73  _BLOCKED]).** is
9180: 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
9190: 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
91a0: 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
91b0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  ..** If the busy
91c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
91d0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a   NULL, then the.
91e0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c  ** callback will
91f0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
9200: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20   two arguments. 
9210: 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72   The.** first ar
9220: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
9230: 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
9240: 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
9250: 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
9260: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
9270: 65 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74  ent to this rout
9280: 69 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ine.  The second
9290: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
92a0: 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74  the handler is t
92b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
92c0: 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
92d0: 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
92e0: 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
92f0: 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
9300: 65 6e 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62  ent. If the.** b
9310: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
9320: 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
9330: 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
9340: 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
9350: 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
9360: 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
9370: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
9380: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
9390: 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
93a0: 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
93b0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
93c0: 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
93d0: 72 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  r attempt is mad
93e0: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a  e to open the.**
93f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
9400: 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
9410: 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
9420: 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
9430: 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
9440: 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
9450: 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20  ntee that.** it 
9460: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
9470: 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
9480: 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a  ck contention..*
9490: 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  * If SQLite dete
94a0: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
94b0: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
94c0: 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
94d0: 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c  lt in.** a deadl
94e0: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74  ock, it will ret
94f0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
9500: 5d 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f  ] instead..** Co
9510: 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
9520: 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
9530: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
9540: 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
9550: 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
9560: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
9570: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
9580: 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
9590: 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
95a0: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
95b0: 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
95c0: 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
95d0: 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
95e0: 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
95f0: 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
9600: 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
9610: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
9620: 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
9630: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
9640: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
9650: 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
9660: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
9670: 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
9680: 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
9690: 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
96a0: 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
96b0: 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
96c0: 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
96d0: 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
96e0: 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
96f0: 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
9700: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
9710: 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
9720: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
9730: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
9740: 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
9750: 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
9760: 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
9770: 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
9780: 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
9790: 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
97a0: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
97b0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
97c0: 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
97d0: 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
97e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
97f0: 4b 45 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c  KED] when.** SQL
9800: 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
9810: 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
9820: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
9830: 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
9840: 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
9850: 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
9860: 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
9870: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
9880: 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
9890: 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
98a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
98b0: 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
98c0: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
98d0: 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
98e0: 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
98f0: 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
9900: 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
9910: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
9920: 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
9930: 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
9940: 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
9950: 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
9960: 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
9970: 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
9980: 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
9990: 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
99a0: 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
99b0: 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
99c0: 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
99d0: 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
99e0: 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
99f0: 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
9a00: 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
9a10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9a20: 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
9a30: 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
9a40: 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
9a50: 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
9a60: 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
9a70: 2e 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20  . See the.** <a 
9a80: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
9a90: 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74  .sqlite.org/cvst
9aa0: 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
9ab0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
9ac0: 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
9ad0: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
9ae0: 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
9af0: 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
9b00: 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
9b10: 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
9b20: 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c  tant..**..** Sql
9b30: 69 74 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e  ite is re-entran
9b40: 74 2c 20 73 6f 20 74 68 65 20 62 75 73 79 20 68  t, so the busy h
9b50: 61 6e 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74  andler may start
9b60: 20 61 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a   a new query. .*
9b70: 2a 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65  * (It is not cle
9b80: 61 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f  ar why anyone wo
9b90: 75 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 74  uld every want t
9ba0: 6f 20 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69  o do this, but i
9bb0: 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c  t.** is allowed,
9bc0: 20 69 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75   in theory.)  Bu
9bd0: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
9be0: 65 72 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65  er may not close
9bf0: 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
9c00: 2e 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64  .  Closing the d
9c10: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62  atabase from a b
9c20: 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c  usy handler will
9c30: 20 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61   delete .** data
9c40: 20 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20   structures out 
9c50: 66 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65  from under the e
9c60: 78 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61  xecuting query a
9c70: 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62  nd will .** prob
9c80: 61 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61  ably result in a
9c90: 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
9ca0: 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e  ult or other run
9cb0: 74 69 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  time error..**.*
9cc0: 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  * There can only
9cd0: 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
9ce0: 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
9cf0: 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  d for each datab
9d00: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9d10: 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  n.  Setting a ne
9d20: 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
9d30: 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f  lears any previo
9d40: 75 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20  us one..** Note 
9d50: 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
9d60: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
9d70: 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20  ut()] will also 
9d80: 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20  set or clear.** 
9d90: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
9da0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 6f 70 65  ..**.** When ope
9db0: 72 61 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69 74  rating in [sqlit
9dc0: 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
9dd0: 5f 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20  _cache | shared 
9de0: 63 61 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a 20  cache mode],.** 
9df0: 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 62 75  only a single bu
9e00: 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6e 20 62  sy handler can b
9e10: 65 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  e defined for ea
9e20: 63 68 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ch database file
9e30: 2e 0a 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20 64  ..** So if two d
9e40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9e50: 6f 6e 73 20 73 68 61 72 65 20 61 20 73 69 6e 67  ons share a sing
9e60: 6c 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 63  le cache, then c
9e70: 68 61 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20 62  hanging.** the b
9e80: 75 73 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20 6f  usy handler on o
9e90: 6e 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69  ne connection wi
9ea0: 6c 6c 20 61 6c 73 6f 20 63 68 61 6e 67 65 20 74  ll also change t
9eb0: 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
9ec0: 65 72 20 69 6e 20 74 68 65 20 6f 74 68 65 72 20  er in the other 
9ed0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
9ee0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
9ef0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74   invoked.** in t
9f00: 68 65 20 74 68 72 65 61 64 20 74 68 61 74 20 77  he thread that w
9f10: 61 73 20 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20  as running when 
9f20: 74 68 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  the SQLITE_BUSY 
9f30: 77 61 73 20 68 69 74 2e 0a 2a 2f 0a 69 6e 74 20  was hit..*/.int 
9f40: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
9f50: 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
9f60: 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
9f70: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
9f80: 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
9f90: 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
9fa0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
9fb0: 20 73 65 74 73 20 61 20 62 75 73 79 20 68 61 6e   sets a busy han
9fc0: 64 6c 65 72 20 74 68 61 74 20 73 6c 65 65 70 73  dler that sleeps
9fd0: 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65   for a while whe
9fe0: 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20  n a.** table is 
9ff0: 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
a000: 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20  dler will sleep 
a010: 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
a020: 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73  ntil .** at leas
a030: 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
a040: 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20  nds of sleeping 
a050: 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20  have been done. 
a060: 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d   After.** "ms" m
a070: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
a080: 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e  leeping, the han
a090: 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
a0a0: 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b  hich.** causes [
a0b0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
a0c0: 74 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  to return [SQLIT
a0d0: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
a0e0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
a0f0: 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  ]..**.** Calling
a100: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
a110: 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
a120: 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
a130: 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
a140: 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
a150: 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
a160: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
a170: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
a180: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
a190: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
a1a0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
a1b0: 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
a1c0: 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65  y handler was de
a1d0: 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e  fined  .** (usin
a1e0: 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
a1f0: 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
a200: 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
a210: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
a220: 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
a230: 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
a240: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a250: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
a260: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
a270: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a280: 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
a290: 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
a2a0: 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
a2b0: 20 54 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69   This next routi
a2c0: 6e 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ne is a convenie
a2d0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
a2e0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  nd [sqlite3_exec
a2f0: 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20  ()]..** Instead 
a300: 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73  of invoking a us
a310: 65 72 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c  er-supplied call
a320: 62 61 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f  back for each ro
a330: 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75  w of the.** resu
a340: 6c 74 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  lt, this routine
a350: 20 72 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20   remembers each 
a360: 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
a370: 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f  t in memory.** o
a380: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a390: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
a3a0: 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c   then returns al
a3b0: 6c 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  l of the result 
a3c0: 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65  after the.** que
a3d0: 72 79 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e  ry has finished.
a3e0: 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78   .**.** As an ex
a3f0: 61 6d 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74  ample, suppose t
a400: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  he query result 
a410: 77 68 65 72 65 20 74 68 69 73 20 74 61 62 6c 65  where this table
a420: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
a430: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
a440: 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
a450: 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
a460: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
a470: 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
a480: 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
a490: 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
a4a0: 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
a4b0: 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
a4c0: 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
a4d0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
a4e0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
a4f0: 20 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26   argument were &
a500: 61 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66  azResult then af
a510: 74 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ter the function
a520: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65   returns.** azRe
a530: 73 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69  sult will contai
a540: 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
a550: 64 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  data:.**.** <blo
a560: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
a570: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
a580: 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
a590: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
a5a0: 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
a5b0: 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
a5c0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
a5d0: 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
a5e0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
a5f0: 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
a600: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
a610: 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
a620: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
a630: 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
a640: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
a650: 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
a660: 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
a670: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
a680: 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
a690: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
a6a0: 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74  *.** Notice that
a6b0: 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 78 74   there is an ext
a6c0: 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63  ra row of data c
a6d0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f  ontaining the co
a6e0: 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e  lumn.** headers.
a6f0: 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20    But the *nrow 
a700: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20  return value is 
a710: 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75  still 3.  *ncolu
a720: 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20  mn is.** set to 
a730: 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20  2.  In general, 
a740: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
a750: 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e  lues inserted in
a760: 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77  to azResult.** w
a770: 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20  ill be ((*nrow) 
a780: 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e  + 1)*(*ncolumn).
a790: 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
a7a0: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
a7b0: 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  n has finished u
a7c0: 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c  sing the result,
a7d0: 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70   it should .** p
a7e0: 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 64  ass the result d
a7f0: 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ata pointer to s
a800: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
a810: 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  e() in order to 
a820: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
a830: 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
a840: 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61  malloc-ed.  Beca
a850: 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
a860: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
a870: 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
a880: 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  s, the calling f
a890: 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
a8a0: 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a   try to call .**
a8b0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
a8c0: 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
a8d0: 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  y [sqlite3_free_
a8e0: 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
a8f0: 20 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20   to release .** 
a900: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
a910: 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
a920: 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
a930: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
a940: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 73 61  outine is the sa
a950: 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69  me as from [sqli
a960: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a  te3_exec()]..*/.
a970: 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
a980: 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
a990: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
a9a0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
a9b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
a9c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
a9d0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65  /* SQL to be exe
a9e0: 63 75 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  cuted */.  char 
a9f0: 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20  ***resultp,     
aa00: 20 20 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74    /* Result writ
aa10: 74 65 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b  ten to a char *[
aa20: 5d 20 20 74 68 61 74 20 74 68 69 73 20 70 6f 69  ]  that this poi
aa30: 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20  nts to */.  int 
aa40: 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20  *nrow,          
aa50: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
aa60: 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
aa70: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
aa80: 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20  t *ncolumn,     
aa90: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
aaa0: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
aab0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
aac0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
aad0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
aae0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
aaf0: 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
ab00: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
ab10: 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
ab20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ab30: 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
ab40: 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
ab50: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
ab60: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
ab70: 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68  workalikes of th
ab80: 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
ab90: 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
aba0: 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
abb0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
abc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
abd0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
abe0: 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
abf0: 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
ac00: 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
ac10: 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
ac20: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
ac30: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ac40: 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
ac50: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
ac60: 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
ac70: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
ac80: 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
ac90: 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68  3_free()].  Both
aca0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
acb0: 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
acc0: 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
acd0: 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
ace0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
acf0: 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
ad00: 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
ad10: 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
ad20: 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73  .** In sqlite3_s
ad30: 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
ad40: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
ad50: 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
ad60: 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
ad70: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
ad80: 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
ad90: 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
ada0: 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
adb0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
adc0: 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
add0: 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
ade0: 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
adf0: 6d 65 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61  meter.  Note tha
ae00: 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
ae10: 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
ae20: 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
ae30: 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
ae40: 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73  intf().  This is
ae50: 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
ae60: 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
ae70: 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
ae80: 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
ae90: 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
aea0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f  mpatibility.  No
aeb0: 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
aec0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
aed0: 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
aee0: 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
aef0: 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
af00: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
af10: 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
af20: 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
af30: 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20  the buffer.  We 
af40: 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
af50: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
af60: 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
af70: 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
af80: 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
af90: 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
afa0: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
afb0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
afc0: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
afd0: 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
afe0: 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
aff0: 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
b000: 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   As long as the 
b010: 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
b020: 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
b030: 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
b040: 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
b050: 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
b060: 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
b070: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o-terminated.  T
b080: 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
b090: 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
b0a0: 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
b0b0: 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
b0c0: 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
b0d0: 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
b0e0: 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
b0f0: 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
b100: 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
b110: 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
b120: 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
b130: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
b140: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
b150: 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
b160: 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
b170: 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
b180: 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
b190: 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
b1a0: 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
b1b0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
b1c0: 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72  usual printf for
b1d0: 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
b1e0: 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
b1f0: 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
b200: 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
b210: 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
b220: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20  s..**.** The %q 
b230: 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
b240: 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
b250: 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
b260: 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
b270: 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
b280: 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
b290: 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
b2a0: 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
b2b0: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
b2c0: 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
b2d0: 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
b2e0: 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42  ring literal.  B
b2f0: 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
b300: 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
b310: 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
b320: 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
b330: 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
b340: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
b350: 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
b360: 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
b370: 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76  so some string v
b380: 61 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73  ariable contains
b390: 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
b3a0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
b3b0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
b3c0: 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
b3d0: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
b3e0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
b3f0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
b400: 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
b410: 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
b420: 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
b430: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
b440: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
b450: 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
b460: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
b470: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
b480: 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
b490: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
b4a0: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
b4b0: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
b4c0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
b4d0: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
b4e0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
b4f0: 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
b500: 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
b510: 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
b520: 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
b530: 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
b540: 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
b550: 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
b560: 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
b570: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
b580: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
b590: 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
b5a0: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
b5b0: 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
b5c0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
b5d0: 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
b5e0: 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
b5f0: 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
b600: 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
b610: 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
b620: 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
b630: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
b640: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
b650: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
b660: 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
b670: 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
b680: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
b690: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
b6a0: 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
b6b0: 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
b6c0: 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
b6d0: 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20  ral rule you.** 
b6e0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73  should always us
b6f0: 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
b700: 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
b710: 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
b720: 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c  ring .** literal
b730: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
b740: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
b750: 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
b760: 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
b770: 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
b780: 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
b790: 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
b7a0: 20 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61    Or if the para
b7b0: 6d 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67  meter in the arg
b7c0: 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73  ument.** list is
b7d0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
b7e0: 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
b7f0: 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
b800: 28 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a  (without single.
b810: 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c  ** quotes) in pl
b820: 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70  ace of the %Q op
b830: 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65  tion.  So, for e
b840: 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
b850: 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
b860: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
b870: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
b880: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
b890: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
b8a0: 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
b8b0: 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
b8c0: 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
b8d0: 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
b8e0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
b8f0: 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
b900: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
b910: 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
b920: 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
b930: 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
b940: 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
b950: 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
b960: 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
b970: 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
b980: 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
b990: 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74   The "%z" format
b9a0: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
b9b0: 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22  s exactly like "
b9c0: 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  %s" with the.** 
b9d0: 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
b9e0: 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
b9f0: 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
ba00: 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
ba10: 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
ba20: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
ba30: 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
ba40: 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2f 0a 63  put string..*/.c
ba50: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
ba60: 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
ba70: 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
ba80: 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
ba90: 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
baa0: 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
bab0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
bac0: 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
bad0: 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
bae0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
baf0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
bb00: 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
bb10: 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
bb20: 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
bb30: 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
bb40: 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
bb50: 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
bb60: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 28 53  cation needs. (S
bb70: 65 65 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e  ee the exception
bb80: 20 62 65 6c 6f 77 2e 29 0a 2a 2a 20 54 68 65 20   below.).** The 
bb90: 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
bba0: 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
bbb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bbc0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
bbd0: 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  s the malloc(), 
bbe0: 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64  realloc().** and
bbf0: 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
bc00: 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
bc10: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48 6f 77   C library.  How
bc20: 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c  ever, if .** SQL
bc30: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
bc40: 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69  with the followi
bc50: 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ng C preprocesso
bc60: 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62  r macro.**.** <b
bc70: 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54  lockquote> SQLIT
bc80: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
bc90: 4c 4f 43 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b  LOCATION </block
bca0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65  quote>.**.** the
bcb0: 6e 20 6e 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n no implementat
bcc0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
bcd0: 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
bce0: 65 73 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e  es by.** SQLite.
bcf0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
bd00: 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  n that links aga
bd10: 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a  inst SQLite is.*
bd20: 2a 20 65 78 70 65 63 74 65 64 20 74 6f 20 70 72  * expected to pr
bd30: 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69 6d  ovide its own im
bd40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 49  plementation.  I
bd50: 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
bd60: 6e 0a 2a 2a 20 64 6f 65 73 20 70 72 6f 76 69 64  n.** does provid
bd70: 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d  e its own implem
bd80: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  entation for the
bd90: 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 74 68 65  se routines, the
bda0: 6e 0a 2a 2a 20 69 74 20 6d 75 73 74 20 61 6c 73  n.** it must als
bdb0: 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
bdc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
bdd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
bde0: 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 2c 20 5b 73  ory_alarm()], [s
bdf0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
be00: 65 64 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  ed()], and.** [s
be10: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
be20: 67 68 77 61 74 65 72 28 29 5d 2e 20 20 54 68 65  ghwater()].  The
be30: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
be40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
be50: 66 6f 72 20 74 68 65 73 65 20 6c 61 73 74 20 74  for these last t
be60: 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 6e 65  hree routines ne
be70: 65 64 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  ed not actually 
be80: 77 6f 72 6b 2c 20 62 75 74 0a 2a 2a 20 73 74 75  work, but.** stu
be90: 62 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 20 6c  b functions at l
bea0: 65 61 73 74 20 61 72 65 20 6e 65 65 64 65 64 20  east are needed 
beb0: 74 6f 20 73 74 61 74 69 73 66 79 20 74 68 65 20  to statisfy the 
bec0: 6c 69 6e 6b 65 72 2e 0a 2a 2a 20 53 51 4c 69 74  linker..** SQLit
bed0: 65 20 6e 65 76 65 72 20 63 61 6c 6c 73 20 5b 73  e never calls [s
bee0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
bef0: 67 68 77 61 74 65 72 28 29 5d 20 69 74 73 65 6c  ghwater()] itsel
bf00: 66 2c 20 62 75 74 0a 2a 2a 20 74 68 65 20 73 79  f, but.** the sy
bf10: 6d 62 6f 6c 20 69 73 20 69 6e 63 6c 75 64 65 64  mbol is included
bf20: 20 69 6e 20 61 20 74 61 62 6c 65 20 61 73 20 70   in a table as p
bf30: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  art of the.** [s
bf40: 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
bf50: 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
bf60: 63 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ce.  The.** [sql
bf70: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
bf80: 6d 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  m()] and [sqlite
bf90: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
bfa0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
bfb0: 72 65 20 63 61 6c 6c 65 64 20 62 79 20 5b 73 71  re called by [sq
bfc0: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
bfd0: 6c 69 6d 69 74 28 29 5d 20 61 6e 64 20 77 6f 72  limit()] and wor
bfe0: 6b 69 6e 67 20 69 6d 70 6c 65 6d 65 6e 74 61 74  king implementat
bff0: 69 6f 6e 73 0a 2a 2a 20 6f 66 20 62 6f 74 68 20  ions.** of both 
c000: 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
c010: 20 70 72 6f 76 69 64 65 64 20 69 66 20 5b 73 71   provided if [sq
c020: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
c030: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 69 73 20 74  limit()].** is t
c040: 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63  o operate correc
c050: 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 45 78  tly..**.** <b>Ex
c060: 63 65 70 74 69 6f 6e 3a 3c 2f 62 3e 20 54 68 65  ception:</b> The
c070: 20 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   windows OS inte
c080: 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
c090: 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
c0a0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
c0b0: 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
c0c0: 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
c0d0: 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
c0e0: 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
c0f0: 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
c100: 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
c110: 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
c120: 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
c130: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
c140: 77 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  windows.** insta
c150: 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
c160: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
c170: 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
c180: 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
c190: 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
c1a0: 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
c1b0: 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
c1c0: 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
c1d0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
c1e0: 45 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  EM]..*/.void *sq
c1f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
c200: 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
c210: 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
c220: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
c230: 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
c240: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c250: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
c260: 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
c270: 2a 2a 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** In addition t
c280: 6f 20 74 68 65 20 62 61 73 69 63 20 74 68 72 65  o the basic thre
c290: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  e allocation rou
c2a0: 74 69 6e 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  tines .** [sqlit
c2b0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
c2c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
c2d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
c2e0: 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 74 68 65 20  lloc()],.** the 
c2f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c300: 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c  n subsystem incl
c310: 75 64 65 64 20 77 69 74 68 20 74 68 65 20 53 51  uded with the SQ
c320: 4c 69 74 65 0a 2a 2a 20 73 6f 75 72 63 65 73 20  Lite.** sources 
c330: 70 72 6f 76 69 64 65 73 20 74 68 65 20 69 6e 74  provides the int
c340: 65 72 66 61 63 65 73 20 73 68 6f 77 6e 20 62 65  erfaces shown be
c350: 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  low..**.** The f
c360: 69 72 73 74 20 6f 66 20 74 68 65 73 65 20 74 77  irst of these tw
c370: 6f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  o routines retur
c380: 6e 73 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ns the amount of
c390: 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 63 75 72 72   memory .** curr
c3a0: 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
c3b0: 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
c3c0: 6e 6f 74 20 66 72 65 65 64 29 2e 20 20 54 68 65  not freed).  The
c3d0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 74 75 72   second.** retur
c3e0: 6e 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  ns the largest i
c3f0: 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 61 6d 6f  nstantaneous amo
c400: 75 6e 74 20 6f 66 20 6f 75 74 73 74 61 6e 64 69  unt of outstandi
c410: 6e 67 0a 2a 2a 20 6d 65 6d 6f 72 79 2e 20 20 54  ng.** memory.  T
c420: 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  he highwater mar
c430: 6b 20 69 73 20 72 65 73 65 74 20 69 66 20 74 68  k is reset if th
c440: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  e argument is.**
c450: 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   true..**.** The
c460: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c470: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
c480: 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  s in the SQLite 
c490: 63 6f 72 65 0a 2a 2a 20 69 73 20 6f 6d 69 74 74  core.** is omitt
c4a0: 65 64 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ed if the applic
c4b0: 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70 69 6c 65  ation is compile
c4c0: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
c4d0: 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
c4e0: 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 6d 61 63 72  _ALLOCATION macr
c4f0: 6f 20 64 65 66 69 6e 65 64 2e 20 20 49 6e 20 74  o defined.  In t
c500: 68 61 74 20 63 61 73 65 2c 0a 2a 2a 20 74 68 65  hat case,.** the
c510: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
c520: 74 20 6c 69 6e 6b 73 20 53 51 4c 69 74 65 20 6d  t links SQLite m
c530: 75 73 74 20 70 72 6f 76 69 64 65 20 69 74 73 20  ust provide its 
c540: 6f 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  own.** alternati
c550: 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
c560: 6e 2e 20 20 53 65 65 20 74 68 65 20 64 6f 63 75  n.  See the docu
c570: 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 0a 2a 2a 20  mentation on.** 
c580: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c590: 29 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  )] for additiona
c5a0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
c5b0: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
c5c0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
c5d0: 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
c5e0: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
c5f0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
c600: 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
c610: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
c620: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
c630: 74 69 6f 6e 20 41 6c 61 72 6d 73 0a 2a 2a 0a 2a  tion Alarms.**.*
c640: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
c650: 65 6d 6f 72 79 5f 61 6c 61 72 6d 5d 20 72 6f 75  emory_alarm] rou
c660: 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20  tine is used to 
c670: 72 65 67 69 73 74 65 72 0a 2a 2a 20 61 20 63 61  register.** a ca
c680: 6c 6c 62 61 63 6b 20 6f 6e 20 6d 65 6d 6f 72 79  llback on memory
c690: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 76 65 6e   allocation even
c6a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ts..**.** This r
c6b0: 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
c6c0: 20 6f 72 20 63 6c 65 61 72 73 20 61 20 63 61 6c   or clears a cal
c6d0: 6c 62 61 63 6b 73 20 74 68 61 74 20 66 69 72 65  lbacks that fire
c6e0: 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 61 6d  s when.** the am
c6f0: 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ount of memory a
c700: 6c 6c 6f 63 61 74 65 64 20 65 78 63 65 65 64 73  llocated exceeds
c710: 20 69 54 68 72 65 73 68 6f 6c 64 2e 20 20 4f 6e   iThreshold.  On
c720: 6c 79 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63  ly.** a single c
c730: 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62 65 20 72  allback can be r
c740: 65 67 69 73 74 65 72 65 64 20 61 74 20 61 20 74  egistered at a t
c750: 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 0a  ime.  Each call.
c760: 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ** to [sqlite3_m
c770: 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 20 6f  emory_alarm()] o
c780: 76 65 72 77 72 69 74 65 73 20 74 68 65 20 70 72  verwrites the pr
c790: 65 76 69 6f 75 73 20 63 61 6c 6c 62 61 63 6b 2e  evious callback.
c7a0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
c7b0: 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
c7c0: 73 65 74 74 69 6e 67 20 78 43 61 6c 6c 62 61 63  setting xCallbac
c7d0: 6b 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  k to a NULL.** p
c7e0: 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54  ointer..** .** T
c7f0: 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  he parameters to
c800: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
c810: 65 20 74 68 65 20 70 41 72 67 20 76 61 6c 75 65  e the pArg value
c820: 2c 20 74 68 65 20 0a 2a 2a 20 61 6d 6f 75 6e 74  , the .** amount
c830: 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
c840: 6e 74 6c 79 20 69 6e 20 75 73 65 2c 20 61 6e 64  ntly in use, and
c850: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c860: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  .** allocation t
c870: 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
c880: 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 20   callback.  The 
c890: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 2a 2a  callback will.**
c8a0: 20 70 72 65 73 75 6d 61 62 6c 79 20 69 6e 76 6f   presumably invo
c8b0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
c8c0: 28 29 5d 20 74 6f 20 66 72 65 65 20 75 70 20 6d  ()] to free up m
c8d0: 65 6d 6f 72 79 20 73 70 61 63 65 2e 0a 2a 2a 20  emory space..** 
c8e0: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  The callback may
c8f0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
c900: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
c910: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
c920: 5d 0a 2a 2a 20 62 75 74 20 69 66 20 69 74 20 64  ].** but if it d
c930: 6f 65 73 2c 20 6e 6f 20 61 64 64 69 74 69 6f 6e  oes, no addition
c940: 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 77 69 6c  al callbacks wil
c950: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 0a  l be invoked by.
c960: 2a 2a 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ** the recursive
c970: 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   calls..**.** Th
c980: 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  e [sqlite3_soft_
c990: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  heap_limit()] in
c9a0: 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 62 79  terface works by
c9b0: 20 72 65 67 69 73 74 65 72 69 6e 67 0a 2a 2a 20   registering.** 
c9c0: 61 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 61  a memory alarm a
c9d0: 74 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  t the soft heap 
c9e0: 6c 69 6d 69 74 20 61 6e 64 20 69 6e 76 6f 6b 69  limit and invoki
c9f0: 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
ca00: 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
ca10: 5d 20 69 6e 20 74 68 65 20 61 6c 61 72 6d 20 63  ] in the alarm c
ca20: 61 6c 6c 62 61 63 6b 2e 20 20 41 70 70 6c 69 63  allback.  Applic
ca30: 61 74 69 6f 6e 0a 2a 2a 20 70 72 6f 67 72 61 6d  ation.** program
ca40: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 61 74 74  s should not att
ca50: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
ca60: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
ca70: 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65  alarm()].** inte
ca80: 72 66 61 63 65 20 62 65 63 61 75 73 65 20 64 6f  rface because do
ca90: 69 6e 67 20 73 6f 20 77 69 6c 6c 20 69 6e 74 65  ing so will inte
caa0: 72 66 65 72 65 20 77 69 74 68 20 74 68 65 0a 2a  rfere with the.*
cab0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  * [sqlite3_soft_
cac0: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 6d 6f  heap_limit()] mo
cad0: 64 75 6c 65 2e 20 20 54 68 69 73 20 69 6e 74 65  dule.  This inte
cae0: 72 66 61 63 65 20 69 73 20 65 78 70 6f 73 65 64  rface is exposed
caf0: 0a 2a 2a 20 6f 6e 6c 79 20 73 6f 20 74 68 61 74  .** only so that
cb00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61   applications ca
cb10: 6e 20 70 72 6f 76 69 64 65 20 74 68 65 69 72 20  n provide their 
cb20: 6f 77 6e 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  own.** alternati
cb30: 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
cb40: 6e 20 77 68 65 6e 20 74 68 65 20 53 51 4c 69 74  n when the SQLit
cb50: 65 20 63 6f 72 65 20 69 73 0a 2a 2a 20 63 6f 6d  e core is.** com
cb60: 70 69 6c 65 64 20 77 69 74 68 20 53 51 4c 49 54  piled with SQLIT
cb70: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
cb80: 4c 4f 43 41 54 49 4f 4e 2e 0a 2a 2f 0a 69 6e 74  LOCATION..*/.int
cb90: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
cba0: 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64 28 2a 78  alarm(.  void(*x
cbb0: 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 20 2a  Callback)(void *
cbc0: 70 41 72 67 2c 20 73 71 6c 69 74 65 33 5f 69 6e  pArg, sqlite3_in
cbd0: 74 36 34 20 75 73 65 64 2c 20 69 6e 74 20 4e 29  t64 used, int N)
cbe0: 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a  ,.  void *pArg,.
cbf0: 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
cc00: 69 54 68 72 65 73 68 6f 6c 64 0a 29 3b 0a 0a 0a  iThreshold.);...
cc10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
cc20: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
cc30: 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
cc40: 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  acks.***.** This
cc50: 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
cc60: 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
cc70: 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74 68  callback with th
cc80: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
cc90: 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .  .** The autho
cca0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
ccb0: 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
ccc0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
ccd0: 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
cce0: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
ccf0: 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
cd00: 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
cd10: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
cd20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
cd30: 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
cd40: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
cd50: 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
cd60: 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
cd70: 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
cd80: 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
cd90: 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
cda0: 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
cdb0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
cdc0: 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
cdd0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
cde0: 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
cdf0: 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
ce00: 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
ce10: 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
ce20: 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
ce30: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49  d.** return SQLI
ce40: 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74  TE_OK to allow t
ce50: 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
ce60: 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
ce70: 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
ce80: 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
ce90: 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
cea0: 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
ceb0: 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
cec0: 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
ced0: 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
cee0: 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
cef0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
cf00: 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
cf10: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a  th an error.  .*
cf20: 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e 67 20 6f  *.** Depending o
cf30: 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 74 68  n the action, th
cf40: 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
cf50: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45  ] and [SQLITE_DE
cf60: 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a 20 63 6f  NY] return.** co
cf70: 64 65 73 20 6d 69 67 68 74 20 6d 65 61 6e 20 73  des might mean s
cf80: 6f 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72 65  omething differe
cf90: 6e 74 20 6f 72 20 74 68 65 79 20 6d 69 67 68 74  nt or they might
cfa0: 20 6d 65 61 6e 20 74 68 65 20 73 61 6d 65 0a 2a   mean the same.*
cfb0: 2a 20 74 68 69 6e 67 2e 20 20 49 66 20 74 68 65  * thing.  If the
cfc0: 20 61 63 74 69 6f 6e 20 69 73 2c 20 66 6f 72 20   action is, for 
cfd0: 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70 65 72 66  example, to perf
cfe0: 6f 72 6d 20 61 20 64 65 6c 65 74 65 20 6f 70 65  orm a delete ope
cff0: 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b  rtion,.** then [
d000: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61  SQLITE_IGNORE] a
d010: 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  nd [SQLITE_DENY]
d020: 20 62 6f 74 68 20 63 61 75 73 65 20 74 68 65 20   both cause the 
d030: 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
d040: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c  ation.** to fail
d050: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
d060: 20 42 75 74 20 69 66 20 74 68 65 20 61 63 74 69   But if the acti
d070: 6f 6e 20 69 73 20 74 6f 20 72 65 61 64 20 61 20  on is to read a 
d080: 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 0a  specific column.
d090: 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65 63 69 66  ** from a specif
d0a0: 69 63 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 5b  ic table, then [
d0b0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 77 69 6c  SQLITE_DENY] wil
d0c0: 6c 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  l cause the enti
d0d0: 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  re.** statement 
d0e0: 74 6f 20 66 61 69 6c 20 62 75 74 20 5b 53 51 4c  to fail but [SQL
d0f0: 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77 69 6c 6c  ITE_IGNORE] will
d100: 20 63 61 75 73 65 20 61 20 4e 55 4c 4c 20 76 61   cause a NULL va
d110: 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20 72 65 61  lue to be.** rea
d120: 64 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  d instead of the
d130: 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d 6e 20 76   actual column v
d140: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
d150: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
d160: 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
d170: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
d180: 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74  copy of.** the t
d190: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
d1a0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
d1b0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
d1c0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65  nterface..** The
d1d0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
d1e0: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
d1f0: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
d200: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  .** [SQLITE_COPY
d210: 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
d220: 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
d230: 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
d240: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75  tion.** to be au
d250: 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 61  thorized.  The a
d260: 76 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e 20  vailable action 
d270: 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 51  codes are.** [SQ
d280: 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 75  LITE_COPY | docu
d290: 6d 65 6e 74 65 64 20 73 65 70 61 72 61 74 65 6c  mented separatel
d2a0: 79 5d 2e 20 20 54 68 65 20 74 68 69 72 64 20 74  y].  The third t
d2b0: 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20  hrough sixth.** 
d2c0: 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
d2d0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 73  e callback are s
d2e0: 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
d2f0: 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
d300: 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
d310: 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
d320: 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
d330: 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
d340: 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72   is used when pr
d350: 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74  eparing SQL stat
d360: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
d370: 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72  ntrusted.** sour
d380: 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
d390: 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
d3a0: 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79  ments do not try
d3b0: 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a   to access data.
d3c0: 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65  ** that they are
d3d0: 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
d3e0: 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
d3f0: 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a  y do not try to.
d400: 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  ** execute malic
d410: 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
d420: 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
d430: 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
d440: 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
d450: 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
d460: 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
d470: 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
d480: 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
d490: 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
d4a0: 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
d4b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
d4c0: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
d4d0: 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
d4e0: 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
d4f0: 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
d500: 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
d510: 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
d520: 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
d530: 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
d540: 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
d550: 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
d560: 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61  ing prepared tha
d570: 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  t disallows ever
d580: 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74  ything.** except
d590: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
d5a0: 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  ts.  .**.** Only
d5b0: 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
d5c0: 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
d5d0: 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
d5e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
d5f0: 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
d600: 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
d610: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
d620: 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
d630: 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
d640: 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69    A NULL authori
d650: 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
d660: 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
d670: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ** callback is i
d680: 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 64 65 66  nvoked.  The def
d690: 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
d6a0: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e  is NULL..**.** N
d6b0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
d6c0: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
d6d0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
d6e0: 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c   during .** [sql
d6f0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
d700: 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
d710: 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
d720: 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
d730: 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
d740: 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
d750: 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
d760: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
d770: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
d780: 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
d790: 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
d7a0: 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
d7b0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
d7c0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
d7d0: 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
d7e0: 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
d7f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d800: 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
d810: 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
d820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
d830: 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
d840: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
d850: 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
d860: 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
d870: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
d880: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
d890: 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
d8a0: 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
d8b0: 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
d8c0: 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
d8d0: 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
d8e0: 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
d8f0: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
d900: 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
d910: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
d920: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
d930: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
d940: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d950: 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
d960: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
d970: 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
d980: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
d990: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
d9a0: 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
d9b0: 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
d9c0: 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
d9d0: 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
d9e0: 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
d9f0: 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
da00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
da10: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
da20: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
da30: 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
da40: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
da50: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
da60: 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63   to authorizer c
da70: 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
da80: 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
da90: 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
daa0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
dab0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
dac0: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
dad0: 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
dae0: 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
daf0: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
db00: 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
db10: 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
db20: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
db30: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
db40: 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
db50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
db60: 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
db70: 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
db80: 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
db90: 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f   to be .** autho
dba0: 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
dbb0: 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
dbc0: 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
dbd0: 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
dbe0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  .** function wil
dbf0: 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
dc00: 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
dc10: 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
dc20: 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
dc30: 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
dc40: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
dc50: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
dc60: 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
dc70: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
dc80: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
dc90: 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
dca0: 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20  n", "temp", .** 
dcb0: 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
dcc0: 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
dcd0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
dce0: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
dcf0: 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
dd00: 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
dd10: 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
dd20: 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
dd30: 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
dd40: 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
dd50: 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
dd60: 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
dd70: 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
dd80: 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  m .** top-level 
dd90: 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
dda0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ddb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ddc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
ddd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
dde0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
ddf0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
de00: 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
de10: 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
de20: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
de30: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
de40: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
de50: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
de60: 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
de70: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
de80: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
de90: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
dea0: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
deb0: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
dec0: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
ded0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
dee0: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
def0: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
df00: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
df10: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
df20: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
df30: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
df40: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
df50: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
df60: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
df70: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
df80: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
df90: 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
dfa0: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
dfb0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
dfc0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
dfd0: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
dfe0: 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
dff0: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
e000: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
e010: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e020: 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
e030: 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
e040: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
e050: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
e060: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e070: 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
e080: 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
e090: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
e0a0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e0b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e0c0: 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
e0d0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
e0e0: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
e0f0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
e100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e110: 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
e120: 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
e130: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
e140: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e160: 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
e170: 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
e180: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
e190: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
e1a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
e1b0: 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
e1c0: 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
e1d0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
e1e0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e1f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
e200: 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
e210: 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
e220: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
e230: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
e240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
e250: 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
e260: 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
e270: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
e280: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
e290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
e2a0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
e2b0: 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
e2c0: 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
e2d0: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
e2e0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
e2f0: 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
e300: 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
e310: 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
e320: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e330: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
e340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
e350: 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
e360: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
e370: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e380: 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
e390: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
e3a0: 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
e3b0: 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
e3c0: 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
e3d0: 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
e3e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
e3f0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
e400: 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
e410: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e420: 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
e430: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
e440: 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
e450: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e460: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e470: 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
e480: 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
e490: 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
e4a0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
e4b0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e4c0: 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
e4d0: 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
e4e0: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e4f0: 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
e500: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e510: 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
e520: 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
e530: 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
e540: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
e550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e560: 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
e570: 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
e580: 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
e590: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e5a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e5b0: 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
e5c0: 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
e5d0: 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
e5e0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
e5f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e600: 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
e610: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
e620: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
e630: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e650: 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
e660: 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
e670: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
e680: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
e690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
e6a0: 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
e6b0: 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
e6c0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
e6d0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
e6e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
e6f0: 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
e700: 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
e710: 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
e720: 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
e730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
e740: 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
e750: 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69    31   /* Functi
e760: 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  on Name   NULL  
e770: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
e780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
e790: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e7a0: 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
e7b0: 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
e7c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
e7d0: 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
e7e0: 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
e7f0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
e800: 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
e810: 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
e820: 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
e830: 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
e840: 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
e850: 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
e860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54  statements..** T
e870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
e880: 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
e890: 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
e8a0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
e8b0: 20 61 74 20 74 68 65 20 66 69 72 73 74 20 5b 73   at the first [s
e8c0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
e8d0: 6f 72 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  or the evaluatio
e8e0: 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  n of an SQL stat
e8f0: 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61  ement..** The ca
e900: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
e910: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
e920: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
e930: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
e940: 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
e950: 65 6e 74 20 66 69 6e 69 73 68 65 73 20 61 6e 64  ent finishes and
e960: 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e 66   includes.** inf
e970: 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20  ormation on how 
e980: 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
e990: 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ent ran..**.** T
e9a0: 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
e9b0: 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
e9c0: 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
e9d0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
e9e0: 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
e9f0: 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f  to change..*/.vo
ea00: 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
ea10: 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
ea20: 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
ea30: 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
ea40: 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
ea50: 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
ea60: 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
ea70: 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
ea80: 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
ea90: 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
eaa0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
eab0: 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
eac0: 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
ead0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
eae0: 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
eaf0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
eb00: 2d 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  - the progress c
eb10: 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 0a 2a  allback - that.*
eb20: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  * is invoked per
eb30: 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
eb40: 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
eb50: 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
eb60: 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  exec()],.** [sql
eb70: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
eb80: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
eb90: 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
eba0: 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
ebb0: 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69   .** interface i
ebc0: 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
ebd0: 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
ebe0: 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
ebf0: 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
ec00: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
ec10: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
ec20: 65 72 79 20 4e 20 76 69 72 74 75 61 6c 20 6d 61  ery N virtual ma
ec30: 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 0a 2a  chine opcodes,.*
ec40: 2a 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  * where N is the
ec50: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
ec60: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
ec70: 6e 2e 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  n. The progress 
ec80: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 74 73 65  callback.** itse
ec90: 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
eca0: 20 62 79 20 74 68 65 20 74 68 69 72 64 20 61 72   by the third ar
ecb0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
ecc0: 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f 75  unction. The fou
ecd0: 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rth.** argument 
ece0: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
ecf0: 20 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74   is a void point
ed00: 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
ed10: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
ed20: 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65  ck.** function e
ed30: 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
ed40: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nvoked..**.** If
ed50: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
ed60: 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
ed70: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f  lite3_step()], o
ed80: 72 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  r [sqlite3_get_t
ed90: 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65 73 75 6c  able()].** resul
eda0: 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e  ts in fewer than
edb0: 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67   N opcodes being
edc0: 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20   executed, then 
edd0: 74 68 65 20 70 72 6f 67 72 65 73 73 20 0a 2a 2a  the progress .**
ede0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76   callback is nev
edf0: 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a  er invoked..** .
ee00: 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
ee10: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
ee20: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
ee30: 62 65 20 72 65 67 69 73 74 65 72 65 64 20 66 6f  be registered fo
ee40: 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64  r each.** open d
ee50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ee60: 6f 6e 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20  on.  Every call 
ee70: 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
ee80: 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
ee90: 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
eea0: 72 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70  results of the p
eeb0: 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a  revious call..**
eec0: 20 54 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 70   To remove the p
eed0: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
eee0: 20 61 6c 74 6f 67 65 74 68 65 72 2c 20 70 61 73   altogether, pas
eef0: 73 20 4e 55 4c 4c 20 61 73 20 74 68 65 20 74 68  s NULL as the th
ef00: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
ef10: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
ef20: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70  ..**.** If the p
ef30: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
ef40: 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
ef50: 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20  t other than 0, 
ef60: 74 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74  then the current
ef70: 20 0a 2a 2a 20 71 75 65 72 79 20 69 73 20 69 6d   .** query is im
ef80: 6d 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69 6e  mediately termin
ef90: 61 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61 74  ated and any dat
efa0: 61 62 61 73 65 20 63 68 61 6e 67 65 73 20 72 6f  abase changes ro
efb0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 54 68  lled back..** Th
efc0: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71  e containing [sq
efd0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
efe0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
eff0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
f000: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c  get_table()] cal
f010: 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  l returns SQLITE
f020: 5f 49 4e 54 45 52 52 55 50 54 2e 20 20 20 54 68  _INTERRUPT.   Th
f030: 69 73 20 66 65 61 74 75 72 65 0a 2a 2a 20 63 61  is feature.** ca
f040: 6e 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  n be used, for e
f050: 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d 70 6c 65  xample, to imple
f060: 6d 65 6e 74 20 74 68 65 20 22 43 61 6e 63 65 6c  ment the "Cancel
f070: 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a  " button on a.**
f080: 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
f090: 20 62 6f 78 20 69 6e 20 61 20 47 55 49 2e 0a 2a   box in a GUI..*
f0a0: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
f0b0: 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
f0c0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
f0d0: 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
f0e0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
f0f0: 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
f100: 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
f110: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f  nnection.**.** O
f120: 70 65 6e 20 74 68 65 20 73 71 6c 69 74 65 20 64  pen the sqlite d
f130: 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 66 69  atabase file "fi
f140: 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65 20 22 66  lename".  The "f
f150: 69 6c 65 6e 61 6d 65 22 20 69 73 20 55 54 46 2d  ilename" is UTF-
f160: 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 66 6f 72  8.** encoded for
f170: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f180: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
f190: 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 55 54  pen_v2()] and UT
f1a0: 46 2d 31 36 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  F-16 encoded.** 
f1b0: 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
f1c0: 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71  te order for [sq
f1d0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
f1e0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a  .** An [sqlite3*
f1f0: 5d 20 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75  ] handle is retu
f200: 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
f210: 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72  ven.** if an err
f220: 6f 72 20 6f 63 63 75 72 73 2e 20 49 66 20 74 68  or occurs. If th
f230: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
f240: 65 6e 65 64 20 28 6f 72 20 63 72 65 61 74 65 64  ened (or created
f250: 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 0a  ) successfully,.
f260: 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  ** then [SQLITE_
f270: 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
f280: 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
f290: 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
f2a0: 72 6e 65 64 2e 20 54 68 65 0a 2a 2a 20 5b 73 71  rned. The.** [sq
f2b0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
f2c0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
f2d0: 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65  sg16()]  routine
f2e0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
f2f0: 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
f300: 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
f310: 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
f320: 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  e error..**.** T
f330: 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
f340: 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
f350: 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
f360: 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  -8 if.** [sqlite
f370: 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
f380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
f390: 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
f3a0: 2a 20 55 54 46 2d 31 36 20 69 66 20 5b 73 71 6c  * UTF-16 if [sql
f3b0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
f3c0: 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
f3d0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
f3e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
f3f0: 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
f400: 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69  resources associ
f410: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
f420: 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64   [sqlite3*] hand
f430: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
f440: 65 61 73 65 64 20 62 79 20 70 61 73 73 69 6e 67  eased by passing
f450: 20 69 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74   it to.** [sqlit
f460: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
f470: 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
f480: 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
f490: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
f4a0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
f4b0: 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73  ce works like [s
f4c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 65  qlite3_open()] e
f4d0: 78 63 65 70 74 20 74 68 61 74 0a 2a 2a 20 70 72  xcept that.** pr
f4e0: 6f 76 69 64 65 73 20 74 77 6f 20 61 64 64 69 74  ovides two addit
f4f0: 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
f500: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
f510: 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74 68 65  control over the
f520: 0a 2a 2a 20 6e 65 77 20 64 61 74 61 62 61 73 65  .** new database
f530: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
f540: 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
f550: 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f 66 3a  r can be one of:
f560: 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
f570: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f580: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c  N_READONLY].** <
f590: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f5a0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20  N_READWRITE].** 
f5b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f5c0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
f5d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
f5e0: 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ATE].** </ol>.**
f5f0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76 61  .** The first va
f600: 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61  lue opens the da
f610: 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79  tabase read-only
f620: 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
f630: 73 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 70  se does.** not p
f640: 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
f650: 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
f660: 75 72 6e 65 64 2e 20 20 54 68 65 20 73 65 63 6f  urned.  The seco
f670: 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a  nd option opens.
f680: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
f690: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
f6a0: 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
f6b0: 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20  ble, or reading 
f6c0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68  only if.** if th
f6d0: 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
f6e0: 70 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65  protected.  In e
f6f0: 69 74 68 65 72 20 63 61 73 65 20 74 68 65 20 64  ither case the d
f700: 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
f710: 65 61 64 79 0a 2a 2a 20 65 78 69 73 74 20 6f 72  eady.** exist or
f720: 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
f730: 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72  urned.  The thir
f740: 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 20 74  d option opens t
f750: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
f760: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
f770: 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74  riting and creat
f780: 65 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73  es it if it does
f790: 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
f7a0: 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  st..** The third
f7b0: 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61   options is beha
f7c0: 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
f7d0: 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71  ays used for [sq
f7e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
f7f0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
f800: 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  en16()]..**.** I
f810: 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
f820: 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
f830: 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a  en an private.**
f840: 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
f850: 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
f860: 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
f870: 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
f880: 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77  ry.** database w
f890: 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 20  ill vanish when 
f8a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
f8b0: 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
f8c0: 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
f8d0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
f8e0: 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65 20 6f  might make use o
f8f0: 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
f900: 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a  cial filenames.*
f910: 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  * that begin wit
f920: 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
f930: 74 65 72 2e 20 20 49 74 20 69 73 20 72 65 63 6f  ter.  It is reco
f940: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a  mmended that .**
f950: 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
f960: 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79   filename really
f970: 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
f980: 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79 6f 75  .** ":" that you
f990: 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
f9a0: 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
f9b0: 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74  name like "./" t
f9c0: 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69 67  o.** avoid ambig
f9d0: 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
f9e0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
f9f0: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
fa00: 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 20 74  then a private t
fa10: 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
fa20: 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
fa30: 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
fa40: 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
fa50: 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
fa60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
fa70: 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
fa80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
fa90: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
faa0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
fab0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
fac0: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
fad0: 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
fae0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
faf0: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
fb00: 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
fb10: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
fb20: 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74   .** interface t
fb30: 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74 61  hat the new data
fb40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
fb50: 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
fb60: 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
fb70: 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c  rameter is a NUL
fb80: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
fb90: 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
fba0: 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65  te3_vfs].** obje
fbb0: 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
fbc0: 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e  * <b>Note to win
fbd0: 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
fbe0: 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
fbf0: 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
fc00: 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
fc10: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  of [sqlite3_open
fc20: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
fc30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74  _open_v2()] must
fc40: 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
fc50: 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
fc60: 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
fc70: 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
fc80: 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
fc90: 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
fca0: 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
fcb0: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
fcc0: 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
fcd0: 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
fce0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  o.** [sqlite3_op
fcf0: 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
fd00: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  3_open_v2()]..*/
fd10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
fd20: 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
fd30: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
fd40: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
fd50: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
fd60: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
fd70: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
fd80: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
fd90: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
fda0: 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
fdb0: 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
fdc0: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
fdd0: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
fde0: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
fdf0: 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
fe00: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
fe10: 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
fe20: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
fe30: 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
fe40: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
fe50: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
fe60: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
fe70: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
fe80: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
fe90: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
fea0: 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
feb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
fec0: 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
fed0: 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
fee0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
fef0: 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
ff00: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
ff10: 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
ff20: 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
ff30: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ff40: 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
ff50: 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
ff60: 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51  e numeric.** [SQ
ff70: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
ff80: 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
ff90: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
ffa0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
ffb0: 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ode].** for the 
ffc0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
ffd0: 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
ffe0: 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
fff0: 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65  .** with [sqlite
10000 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20  3] handle 'db'. 
10010 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
10020 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
10030 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
10040 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
10050 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
10060 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
10070 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
10080 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  * is undefined. 
10090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
100a0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
100b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
100c0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
100d0 68 2d 6c 61 6e 67 61 75 67 65 0a 2a 2a 20 74 65  h-langauge.** te
100e0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
100f0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
10100 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55  either UTF8 or U
10110 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  TF16 respectivel
10120 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
10130 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
10140 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
10150 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
10160 6c 6c 79 2e 20 20 54 68 65 20 0a 2a 2a 20 73 74  lly.  The .** st
10170 72 69 6e 67 20 6d 61 79 20 62 65 20 6f 76 65 72  ring may be over
10180 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
10190 6f 63 61 74 65 64 20 62 79 20 73 75 62 73 65 71  ocated by subseq
101a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53 51  uent calls to SQ
101b0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  Lite.** interfac
101c0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
101d0 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79  ** Calls to many
101e0 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74   sqlite3_* funct
101f0 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65 72 72  ions set the err
10200 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74 72 69  or code and stri
10210 6e 67 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ng returned.** b
10220 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
10230 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
10240 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b  errmsg()], and [
10250 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
10260 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 77 72 69 74  ()].** (overwrit
10270 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f 75 73  ing the previous
10280 20 76 61 6c 75 65 73 29 2e 20 4e 6f 74 65 20 74   values). Note t
10290 68 61 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hat calls to [sq
102a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
102b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  ,.** [sqlite3_er
102c0 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
102d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
102e0 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  ] themselves do 
102f0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a  not affect the.*
10300 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74  * results of fut
10310 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e  ure invocations.
10320 20 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72    Calls to API r
10330 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20  outines that do 
10340 6e 6f 74 20 72 65 74 75 72 6e 0a 2a 2a 20 61 6e  not return.** an
10350 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
10360 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
10370 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
10380 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74   not.** change t
10390 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65  he error code re
103a0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
103b0 6f 75 74 69 6e 65 2e 20 20 49 6e 74 65 72 66 61  outine.  Interfa
103c0 63 65 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ces that are.** 
103d0 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  not associated w
103e0 69 74 68 20 61 20 73 70 65 63 69 66 69 63 20 64  ith a specific d
103f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10400 6f 6e 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  on (examples:.**
10410 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
10420 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  f()] or [sqlite3
10430 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
10440 61 63 68 65 28 29 5d 20 64 6f 20 6e 6f 74 20 63  ache()] do not c
10450 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
10460 75 72 6e 20 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a  urn code.  .**.*
10470 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74  * Assuming no ot
10480 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  her intervening 
10490 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
104a0 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20 74 68  lls are made, th
104b0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
104c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
104d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73   function is ass
104e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
104f0 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a   same error as.*
10500 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20 72 65  * the strings re
10510 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
10520 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
10530 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
10540 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
10550 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
10560 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
10570 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
10580 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
10590 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
105a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
105b0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
105c0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
105d0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
105e0 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f  **.** Instance o
105f0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
10600 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53  present single S
10610 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
10620 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f  This.** is vario
10630 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
10640 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
10650 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63  ent" or a .** "c
10660 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
10670 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
10680 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
10690 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69  "..** .** The li
106a0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
106b0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
106c0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
106d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
106e0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
106f0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
10700 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
10710 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
10720 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
10730 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
10740 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
10750 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67  parameters using
10760 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
10770 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
10780 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74  lite3_bind_* int
10790 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69  erfaces]..** <li
107a0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
107b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
107c0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
107d0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
107e0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
107f0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
10800 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
10810 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
10820 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
10830 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
10840 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
10850 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
10860 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
10870 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
10880 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
10890 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
108a0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
108b0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
108c0 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
108d0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
108e0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
108f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
10900 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
10910 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
10920 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
10930 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
10940 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
10950 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
10960 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
10970 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
10980 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
10990 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
109a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
109b0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73   .**.** The firs
109c0 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20  t argument "db" 
109d0 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c  is an [sqlite3 |
109e0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
109f0 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74   handle] .** obt
10a00 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
10a10 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
10a20 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
10a30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
10a40 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10a50 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54 68  open16()]..** Th
10a60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10a70 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20  t "zSql" is the 
10a80 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
10a90 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
10aa0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
10ab0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
10ac0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
10ad0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
10ae0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
10af0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
10b00 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c  es UTF-8 and sql
10b10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
10b20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
10b30 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
10b40 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
10b50 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
10b60 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a  gument is less.*
10b70 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  * than zero, the
10b80 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
10b90 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
10ba0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
10bb0 20 49 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73 20   If.** nByte is 
10bc0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
10bd0 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
10be0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a  imum number of .
10bf0 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72  ** bytes read fr
10c00 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
10c10 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
10c20 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
10c30 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
10c40 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
10c50 74 20 27 5c 30 30 30 27 20 63 68 61 72 61 63 74  t '\000' charact
10c60 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20  er or .** until 
10c70 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
10c80 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
10c90 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
10ca0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
10cb0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
10cc0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
10cd0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
10ce0 69 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74  irst.** SQL stat
10cf0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
10d00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
10d10 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66  y compiles the f
10d20 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a  irst statement.*
10d30 2a 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  * in zSql, so *p
10d40 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
10d50 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72  inting to what r
10d60 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
10d70 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
10d80 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
10d90 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
10da0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
10db0 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
10dc0 74 20 73 74 72 75 63 74 75 72 65 5d 20 74 68 61  t structure] tha
10dd0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
10de0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
10df0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
10e00 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
10e10 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d  error, *ppStmt m
10e20 61 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20  ay be.** set to 
10e30 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
10e40 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
10e50 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ed no SQL (if th
10e60 65 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a  e input is and.*
10e70 2a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  * empty string o
10e80 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
10e90 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
10ea0 20 74 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63   to NULL.  The c
10eb0 61 6c 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64  alling.** proced
10ec0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
10ed0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
10ee0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  the compiled SQL
10ef0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73   statement.** us
10f00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
10f10 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
10f20 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
10f30 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ith it..**.** On
10f40 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
10f50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
10f60 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
10f70 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
10f80 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
10f90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
10fa0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10fb0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
10fc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
10fd0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
10fe0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
10ff0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
11000 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
11010 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
11020 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
11030 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
11040 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
11050 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
11060 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
11070 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
11080 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
11090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
110a0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
110b0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
110c0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
110d0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
110e0 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69  y of the .** ori
110f0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
11100 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
11110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11120 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
11130 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72   behave a differ
11140 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79  ently in two way
11150 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
11160 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
11170 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
11180 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
11190 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
111a0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
111b0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
111c0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
111d0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
111e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
111f0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
11200 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
11210 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
11220 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
11230 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
11240 20 69 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61   in a way.** tha
11250 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
11260 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
11270 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
11280 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
11290 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
112a0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
112b0 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
112c0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
112d0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
112e0 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
112f0 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
11300 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11310 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
11320 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
11330 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
11340 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
11350 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
11360 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
11370 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a   of the parsing.
11380 2a 2a 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ** error that re
11390 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
113a0 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
113b0 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
113c0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
113d0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
113e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
113f0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
11400 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
11410 61 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54  ailed .** [SQLIT
11420 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
11430 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53   codes] or.** [S
11440 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
11450 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
11460 6c 74 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61  lt codes] such a
11470 73 20 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54  s directly..** T
11480 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
11490 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c  or was that [sql
114a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
114b0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
114c0 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c   generic.** [SQL
114d0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
114e0 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77  t code and you w
114f0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
11500 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
11510 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
11520 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
11530 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
11540 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
11550 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a   the problem..**
11560 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
11570 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65  repare interface
11580 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
11590 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
115a0 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74   error is.** ret
115b0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
115c0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
115d0 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
115e0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
115f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
11600 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
11610 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
11620 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
11630 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
11640 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
11650 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
11660 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
11670 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
11680 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
11690 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
116a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
116b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
116c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
116d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
116e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
116f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
11700 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
11710 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
11720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
11730 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
11740 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
11750 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
11760 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
11770 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
11780 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
11790 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
117a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
117b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
117c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
117d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
117e0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
117f0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
11800 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
11810 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
11820 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
11830 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
11840 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
11850 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
11860 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
11870 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
11880 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
11890 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
118a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
118b0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
118c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
118d0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
118e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
118f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
11900 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
11910 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
11920 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
11930 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
11940 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
11950 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
11960 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
11970 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
11980 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
11990 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
119a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
119b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
119c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
119d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
119e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
119f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
11a00 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
11a10 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
11a20 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
11a30 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
11a40 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
11a50 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
11a60 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
11a70 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
11a80 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
11a90 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
11aa0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
11ab0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
11ac0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
11ad0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
11ae0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
11af0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11b00 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79    Dynamically Ty
11b10 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
11b20 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
11b30 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
11b40 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  g for the values
11b50 20 69 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c   it stores.  Val
11b60 75 65 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69  ues can .** be i
11b70 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
11b80 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
11b90 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
11ba0 6f 72 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a  or NULL.  When.*
11bb0 2a 20 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64  * passing around
11bc0 20 76 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c   values internal
11bd0 6c 79 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69  ly, each value i
11be0 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
11bf0 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  .** an instance 
11c00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
11c10 61 6c 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  alue object..*/.
11c20 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
11c30 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
11c40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11c50 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  F:  SQL Function
11c60 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
11c70 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
11c80 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
11c90 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
11ca0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
11cb0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
11cc0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
11cd0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63  A pointer to suc
11ce0 68 20 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74  h an object is t
11cf0 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61  he.** first para
11d00 6d 65 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65  meter to user-de
11d10 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
11d20 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ons..*/.typedef 
11d30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
11d40 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
11d50 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
11d60 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e  API3REF:  Bindin
11d70 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
11d80 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
11d90 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
11da0 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
11db0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
11dc0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
11dd0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e   variants,.** on
11de0 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61  e or more litera
11df0 6c 73 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63  ls can be replac
11e00 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72  e by a parameter
11e10 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
11e20 0a 2a 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  .** forms:.**.**
11e30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
11e40 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
11e50 2a 20 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20  * <li>  :AAA.** 
11e60 3c 6c 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c  <li>  @AAA.** <l
11e70 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
11e80 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
11e90 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
11ea0 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
11eb0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
11ec0 65 72 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20  eral,.** AAA is 
11ed0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
11ee0 69 64 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56  identifier and V
11ef0 56 56 20 69 73 20 61 20 76 61 72 69 61 62 6c 65  VV is a variable
11f00 20 6e 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a   name according.
11f10 2a 2a 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78  ** to the syntax
11f20 20 72 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43   rules of the TC
11f30 4c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61  L programming la
11f40 6e 67 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76  nguage..** The v
11f50 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70  alues of these p
11f60 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
11f70 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
11f80 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a  ameter names").*
11f90 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
11fa0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
11fb0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
11fc0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
11fd0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11fe0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
11ff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
12000 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20  routines always 
12010 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
12020 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
12030 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
12040 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
12050 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
12060 5d 20 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69  ] or.** its vari
12070 61 6e 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e  ants.  The secon
12080 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
12090 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
120a0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  e parameter to b
120b0 65 20 73 65 74 2e 20 20 54 68 65 20 66 69 72 73  e set.  The firs
120c0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a  t parameter has.
120d0 2a 2a 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  ** an index of 1
120e0 2e 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20  . When the same 
120f0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
12100 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
12110 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a  n once, second.*
12120 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
12130 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
12140 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
12150 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
12160 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68   occurrence.  Th
12170 65 20 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e  e index for.** n
12180 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
12190 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
121a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
121b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
121c0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50  meter_name()] AP
121d0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
121e0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e  he index for "?N
121f0 4e 4e 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73  NN".** parametes
12200 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
12210 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
12220 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
12230 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
12240 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
12250 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54   parameter SQLIT
12260 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
12270 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76  UMBER (default v
12280 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53  alue: 999)..** S
12290 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69  ee <a href="limi
122a0 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e  ts.html">limits.
122b0 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64  html</a> for add
122c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
122d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ion..**.** The t
122e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
122f0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
12300 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
12310 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
12320 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ose.** routines 
12330 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
12340 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
12350 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
12360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
12370 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
12380 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
12390 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
123a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
123b0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69  s in the.** stri
123c0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
123d0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
123e0 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  .  The number.**
123f0 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e   of bytes does n
12400 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
12410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero-terminator a
12420 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72  t the end of str
12430 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ings..** If the 
12440 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
12450 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
12460 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
12470 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d  string is.** num
12480 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
12490 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
124a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
124b0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
124c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
124d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
124e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
124f0 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
12500 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
12510 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
12520 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
12530 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
12540 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53 51  ** text after SQ
12550 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
12560 64 20 77 69 74 68 20 69 74 2e 20 20 49 66 20 74  d with it.  If t
12570 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
12580 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63  t is the.** spec
12590 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
125a0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
125b0 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73 75  the library assu
125c0 6d 65 73 20 74 68 61 74 20 74 68 65 20 69 6e 66  mes that the inf
125d0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  ormation.** is i
125e0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
125f0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
12600 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
12610 65 20 66 72 65 65 64 2e 20 20 49 66 20 74 68 65  e freed.  If the
12620 0a 2a 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65  .** fifth argume
12630 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
12640 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
12650 4e 54 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  NT], then SQLite
12660 20 6d 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77   makes its.** ow
12670 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
12680 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
12690 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
126a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
126b0 2a 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  *().** routine r
126c0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
126d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
126e0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
126f0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
12700 66 20 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a  f length n that.
12710 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
12720 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f  h zeros.  A zero
12730 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
12740 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
12750 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
12760 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
12770 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  t size) while it
12780 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
12790 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
127a0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
127b0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
127c0 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  -holders for BLO
127d0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
127e0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
127f0 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  tten using .** [
12800 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
12810 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c  n | increment BL
12820 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
12830 2e 20 20 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a  .  A negative.**
12840 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
12850 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
12860 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
12870 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   BLOB..**.** The
12880 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
12890 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
128a0 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
128b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
128c0 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
128d0 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
128e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
128f0 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
12900 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
12910 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
12920 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
12930 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
12940 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
12950 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
12960 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
12970 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
12980 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
12990 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
129a0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
129b0 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
129c0 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
129d0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
129e0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
129f0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
12a00 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
12a10 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
12a20 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
12a30 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
12a40 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73   if malloc fails
12a50 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ..** [SQLITE_MIS
12a60 55 53 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USE] is returned
12a70 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
12a80 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
12a90 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61   a virtual.** ma
12aa0 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
12ab0 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
12ac0 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
12ad0 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
12ae0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
12af0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
12b00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
12b10 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
12b20 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
12b30 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
12b40 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
12b50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
12b60 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
12b70 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
12b80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12b90 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
12ba0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
12bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12bc0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
12bd0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
12be0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
12bf0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
12c00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12c10 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
12c20 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
12c30 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
12c40 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
12c50 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
12c60 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
12c70 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
12c80 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
12c90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
12ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
12cb0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
12cc0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
12cd0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
12ce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12cf0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
12d00 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
12d10 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
12d20 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
12d30 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 73 0a  Host Parameters.
12d40 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
12d50 20 6c 61 72 67 65 73 74 20 68 6f 73 74 20 70 61   largest host pa
12d60 72 61 6d 65 74 65 72 20 69 6e 64 65 78 20 69 6e  rameter index in
12d70 20 74 68 65 20 70 72 65 63 6f 6d 70 69 6c 65 64   the precompiled
12d80 20 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65 6e   statement given
12d90 0a 2a 2a 20 61 73 20 74 68 65 20 61 72 67 75 6d  .** as the argum
12da0 65 6e 74 2e 20 20 57 68 65 6e 20 74 68 65 20 68  ent.  When the h
12db0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 61  ost parameters a
12dc0 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20  re of the forms 
12dd0 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a 2a 20 6f  like ":AAA".** o
12de0 72 20 22 3f 22 2c 20 74 68 65 6e 20 74 68 65 79  r "?", then they
12df0 20 61 72 65 20 61 73 73 69 67 6e 65 64 20 73 65   are assigned se
12e00 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 65 61 73  quential increas
12e10 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 65 67 69  ing numbers begi
12e20 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 6e  nning.** with on
12e30 65 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20  e, so the value 
12e40 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
12e50 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
12e60 74 65 72 73 2e 20 20 48 6f 77 65 76 65 72 0a 2a  ters.  However.*
12e70 2a 20 69 66 20 74 68 65 20 73 61 6d 65 20 68 6f  * if the same ho
12e80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
12e90 65 20 69 73 20 75 73 65 64 20 6d 75 6c 74 69 70  e is used multip
12ea0 6c 65 20 74 69 6d 65 73 2c 20 65 61 63 68 20 6f  le times, each o
12eb0 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 69 73 20  ccurrance.** is 
12ec0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  given the same n
12ed0 75 6d 62 65 72 2c 20 73 6f 20 74 68 65 20 76 61  umber, so the va
12ee0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lue returned in 
12ef0 74 68 61 74 20 63 61 73 65 20 69 73 20 74 68 65  that case is the
12f00 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 75 6e   number.** of un
12f10 69 71 75 65 20 68 6f 73 74 20 70 61 72 61 6d 65  ique host parame
12f20 74 65 72 20 6e 61 6d 65 73 2e 20 20 49 66 20 68  ter names.  If h
12f30 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ost parameters o
12f40 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
12f50 22 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 28 77  ".** are used (w
12f60 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69  here NNN is an i
12f70 6e 74 65 67 65 72 29 20 74 68 65 6e 20 74 68 65  nteger) then the
12f80 72 65 20 6d 69 67 68 74 20 62 65 20 67 61 70 73  re might be gaps
12f90 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   in the.** numbe
12fa0 72 69 6e 67 20 61 6e 64 20 74 68 65 20 76 61 6c  ring and the val
12fb0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
12fc0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
12fd0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
12fe0 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72 61 6d 65  e.** host parame
12ff0 74 65 72 20 77 69 74 68 20 74 68 65 20 6c 61 72  ter with the lar
13000 67 65 73 74 20 69 6e 64 65 78 20 76 61 6c 75 65  gest index value
13010 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 70  ..**.** The prep
13020 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d  ared statement m
13030 75 73 74 20 6e 6f 74 20 62 65 20 5b 73 71 6c 69  ust not be [sqli
13040 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
13050 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20 70 72 69  inalized].** pri
13060 6f 72 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  or to this routi
13070 6e 65 20 72 65 74 75 72 6e 6e 69 6e 67 2e 20 20  ne returnning.  
13080 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 72 65  Otherwise the re
13090 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
130a0 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72 6f 62 61  ned.** and proba
130b0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
130c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
130d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
130e0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
130f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
13100 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
13110 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
13120 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
13130 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
13140 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
13150 6f 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  of the n-th para
13160 6d 65 74 65 72 20 69 6e 20 61 20 0a 2a 2a 20 5b  meter in a .** [
13170 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
13180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13190 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20 70 61 72 61  t]..** Host para
131a0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
131b0 72 6d 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  rm ":AAA" or "@A
131c0 41 41 22 20 6f 72 20 22 24 56 56 56 22 20 68 61  AA" or "$VVV" ha
131d0 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20 77 68 69  ve a name.** whi
131e0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
131f0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
13200 22 20 6f 72 20 22 24 56 56 56 22 2e 20 20 0a 2a  " or "$VVV".  .*
13210 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
13220 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
13230 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 0a  " or "$" or "@".
13240 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
13250 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
13260 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72  me..** Parameter
13270 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
13280 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61 76 65  " or "?NNN" have
13290 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20   no name..**.** 
132a0 54 68 65 20 66 69 72 73 74 20 62 6f 75 6e 64 20  The first bound 
132b0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
132c0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
132d0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
132e0 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20   value n is out 
132f0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
13300 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65  he n-th paramete
13310 72 20 69 73 20 6e 61 6d 65 6c 65 73 73 2c 0a 2a  r is nameless,.*
13320 2a 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  * then NULL is r
13330 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65  eturned.  The re
13340 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
13350 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 0a 2a   always in the.*
13360 2a 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  * UTF-8 encoding
13370 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
13380 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
13390 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
133a0 69 66 69 65 64 0a 2a 2a 20 61 73 20 55 54 46 2d  ified.** as UTF-
133b0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
133c0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 20 5b  repare16()] or [
133d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
133e0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
133f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
13400 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
13410 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
13420 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
13430 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
13440 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
13450 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
13460 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
13470 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
13480 69 6e 64 65 78 20 6f 66 20 61 20 68 6f 73 74 20  index of a host 
13490 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74  parameter with t
134a0 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 2e 0a 2a  he given name..*
134b0 2a 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 20  * The name must 
134c0 6d 61 74 63 68 20 65 78 61 63 74 6c 79 2e 20 20  match exactly.  
134d0 49 66 20 6e 6f 20 70 61 72 61 6d 65 74 65 72 20  If no parameter 
134e0 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e  with the given n
134f0 61 6d 65 20 69 73 20 0a 2a 2a 20 66 6f 75 6e 64  ame is .** found
13500 2c 20 72 65 74 75 72 6e 20 30 2e 20 20 50 61 72  , return 0.  Par
13510 61 6d 65 74 65 72 20 6e 61 6d 65 73 20 6d 75 73  ameter names mus
13520 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f 0a 69 6e  t be UTF8..*/.in
13530 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
13540 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
13550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
13560 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
13570 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13580 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
13590 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
135a0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
135b0 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
135c0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
135d0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
135e0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
135f0 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b  t.** reset the [
13600 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
13610 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
13620 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   a .** [sqlite3_
13630 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
13640 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73 65  statement].  Use
13650 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
13660 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68 6f  .** reset all ho
13670 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
13680 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
13690 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
136a0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
136b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
136c0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
136d0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
136e0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 52 65  ult Set.**.** Re
136f0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
13700 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
13710 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
13720 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  urned by the .**
13730 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
13740 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
13750 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72  atement]. This r
13760 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
13770 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20 69 73 20  .** if pStmt is 
13780 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
13790 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
137a0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
137b0 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61 6e 20 55  .** example an U
137c0 50 44 41 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20 73  PDATE)..*/.int s
137d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
137e0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
137f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
13800 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
13810 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
13820 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 54 68  ult Set.**.** Th
13830 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
13840 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
13850 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
13860 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
13870 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
13880 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
13890 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
138a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
138b0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
138c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
138d0 65 72 20 74 6f 20 61 20 55 54 46 38 20 73 74 72  er to a UTF8 str
138e0 69 6e 67 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ing and sqlite3_
138f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a  column_name16().
13900 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
13910 6e 74 65 72 20 74 6f 20 61 20 55 54 46 31 36 20  nter to a UTF16 
13920 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
13930 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
13940 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13950 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
13960 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
13970 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53  implements the S
13980 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
13990 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
139a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
139b0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
139c0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
139d0 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65  lumn is.** numbe
139e0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
139f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
13a00 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
13a10 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
13a20 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
13a30 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
13a40 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
13a50 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
13a60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
13a70 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
13a80 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  xt call sqlite3_
13a90 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
13aa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
13ab0 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74  name16().** on t
13ac0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
13ad0 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
13ae0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
13af0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
13b00 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
13b10 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
13b20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
13b30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
13b40 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
13b50 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
13b60 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
13b70 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  rned..*/.const c
13b80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
13b90 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
13ba0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
13bb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
13bc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
13bd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
13be0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
13bf0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
13c00 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
13c10 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
13c20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
13c30 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
13c40 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61  to determine wha
13c50 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74  t column of what
13c60 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69  .** table in whi
13c70 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65  ch database a re
13c80 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54  sult of a SELECT
13c90 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
13ca0 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
13cb0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
13cc0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
13cd0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
13ce0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
13cf0 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46  er a UTF8 or UTF
13d00 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
13d10 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
13d20 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
13d30 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
13d40 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
13d50 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
13d60 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
13d70 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
13d80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13d90 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
13da0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
13db0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
13dc0 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73   until.** the [s
13dd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
13de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13df0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  ] is destroyed u
13e00 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
13e10 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
13e20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
13e30 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
13e40 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
13e50 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
13e60 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
13e70 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
13e80 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
13e90 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
13ea0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
13eb0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
13ec0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
13ed0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13ee0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
13ef0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
13f00 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
13f10 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
13f20 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  L statement]..**
13f30 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
13f40 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
13f50 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
13f60 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
13f70 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61  d by .** the sta
13f80 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
13f90 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
13fa0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
13fb0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
13fc0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
13fd0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
13fe0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
13ff0 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65  ion.** or subque
14000 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
14010 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
14020 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
14030 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
14040 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77  urn NULL. Otherw
14050 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
14060 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66   the .** name of
14070 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
14080 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e  tabase, table an
14090 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
140a0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ery result.** co
140b0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
140c0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41  ed from..**.** A
140d0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
140e0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
140f0 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69  ose postfixed wi
14100 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 20 55  th "16" return U
14110 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64  TF-16.** encoded
14120 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74   strings, the ot
14130 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
14140 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
14150 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
14160 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14170 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
14180 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
14190 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
141a0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
141b0 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
141c0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
141d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
141e0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
141f0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
14200 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
14210 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
14220 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
14230 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
14240 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
14250 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
14260 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
14270 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
14280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
14290 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
142a0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
142b0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
142c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
142d0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
142e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
142f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
14300 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
14310 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
14320 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
14330 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
14340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
14350 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
14360 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
14370 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
14380 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
14390 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
143a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
143b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
143c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
143d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
143e0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
143f0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
14400 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
14410 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
14420 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
14430 6d 65 74 65 72 20 69 73 20 61 20 5b 73 71 6c 69  meter is a [sqli
14440 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69  te3_stmt | compi
14450 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
14460 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20  t]. .** If this 
14470 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53  statement is a S
14480 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
14490 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
144a0 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65  mn of the .** re
144b0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
144c0 74 20 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43  t  of that SELEC
144d0 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  T is a table col
144e0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
144f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
14500 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
14510 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
14520 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
14530 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
14540 2e 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  . If the Nth col
14550 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
14560 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
14570 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
14580 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
14590 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
145a0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
145b0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
145c0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
145d0 6e 63 6f 64 65 64 2e 20 46 6f 72 20 65 78 61 6d  ncoded. For exam
145e0 70 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64  ple, in.** the d
145f0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
14600 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
14610 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
14620 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65  );.**.** And the
14630 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
14640 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  ment compiled:.*
14650 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
14660 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
14670 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73 20  **.** Then this 
14680 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
14690 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
146a0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
146b0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75  e second.** resu
146c0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  lt column (i==1)
146d0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
146e0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
146f0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
14700 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a  .** (i==0)..**.*
14710 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
14720 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
14730 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20  yping.  So just 
14740 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
14750 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
14760 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
14770 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
14780 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
14790 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
147a0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
147b0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
147c0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
147d0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
147e0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
147f0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
14800 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
14810 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
14820 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
14830 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
14840 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
14850 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
14860 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
14870 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
14880 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
14890 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
148a0 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69  e3_stmt *, int i
148b0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
148c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
148d0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
148e0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
148f0 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20   .** CAPI3REF:  
14900 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
14910 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
14920 41 66 74 65 72 20 61 6e 20 5b 73 71 6c 69 74 65  After an [sqlite
14930 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61  3_stmt | SQL sta
14940 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
14950 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61   prepared with a
14960 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68   call.** to eith
14970 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
14980 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
14990 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
149a0 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20  v2()] or to one 
149b0 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79  of.** the legacy
149c0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
149d0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
149e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
149f0 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65  are16()],.** the
14a00 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  n this function 
14a10 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
14a20 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
14a30 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
14a40 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a   .** statement..
14a50 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
14a60 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
14a70 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65  r of this sqlite
14a80 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
14a90 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
14aa0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
14ab0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
14ac0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
14ad0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
14ae0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
14af0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
14b00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14b10 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
14b20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
14b30 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
14b40 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
14b50 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
14b60 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
14b70 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
14b80 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
14b90 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
14ba0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
14bb0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
14bc0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
14bd0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
14be0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
14bf0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63  .** In the lagac
14c00 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
14c10 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
14c20 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
14c30 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20  LITE_BUSY], .** 
14c40 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
14c50 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
14c60 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
14c70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
14c80 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
14c90 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
14ca0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53   of the other [S
14cb0 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
14cc0 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53  t code].** or [S
14cd0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
14ce0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
14cf0 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62  lt code] might b
14d00 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
14d10 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
14d20 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
14d30 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
14d40 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
14d50 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
14d60 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
14d70 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
14d80 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
14d90 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
14da0 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f  is a COMMIT.** o
14db0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
14dc0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
14dd0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
14de0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
14df0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
14e00 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
14e10 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d  ent is not a COM
14e20 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77  MIT and occurs w
14e30 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
14e40 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
14e50 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
14e60 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
14e70 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
14e80 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
14e90 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
14ea0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
14eb0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
14ec0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
14ed0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
14ee0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
14ef0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
14f00 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
14f10 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
14f20 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
14f30 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
14f40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
14f50 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
14f60 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
14f70 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
14f80 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
14f90 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
14fa0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
14fb0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
14fc0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a  ny data, then .*
14fd0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69  * [SQLITE_ROW] i
14fe0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
14ff0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
15000 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a  f data is ready.
15010 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  ** for processin
15020 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  g by the caller.
15030 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
15040 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
15050 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
15060 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63  3_column_int | c
15070 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
15080 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
15090 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
150a0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
150b0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
150c0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20  row of data..** 
150d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
150e0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
150f0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
15100 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
15110 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
15120 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
15130 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
15140 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
15150 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
15160 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
15170 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
15180 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
15190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
151a0 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
151b0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
151c0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
151d0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
151e0 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51  (example:.** [SQ
151f0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
15200 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
15210 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
15220 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
15230 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
15240 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
15250 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
15260 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  ] on the.** [sql
15270 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
15280 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
15290 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
152a0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
152b0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
152c0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
152d0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
152e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
152f0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
15300 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
15310 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
15320 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
15330 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
15340 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
15350 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 73 71   called on a [sq
15360 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
15370 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
15380 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
15390 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
153a0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
153b0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
153c0 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20  ne that had .** 
153d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
153e0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
153f0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
15400 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
15410 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
15420 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
15430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15440 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
15450 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
15460 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
15470 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
15480 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
15490 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
154a0 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e  Alert:</b>.** In
154b0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
154c0 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73  rface, .** the s
154d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50  qlite3_step() AP
154e0 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
154f0 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
15500 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54   code,.** [SQLIT
15510 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
15520 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74  ing any error ot
15530 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
15540 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53  _BUSY].** and [S
15550 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
15560 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73  You must call [s
15570 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
15580 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
15590 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
155a0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
155b0 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a  of the specific.
155c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
155d0 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
155e0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
155f0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
15600 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
15610 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
15620 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
15630 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
15640 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
15650 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
15660 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
15670 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
15680 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
15690 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
156a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
156b0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
156c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
156d0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
156e0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
156f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
15700 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
15710 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
15720 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69  e .** more speci
15730 66 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  fic [SQLITE_ERRO
15740 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  R | result codes
15750 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
15760 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
15770 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
15780 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
15790 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
157a0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
157b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
157c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
157d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
157e0 3a 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  :.**.** Return t
157f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
15800 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
15810 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
15820 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
15830 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20  After a call to 
15840 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15850 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53   that returns [S
15860 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 69 73  QLITE_ROW], this
15870 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c   routine.** will
15880 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
15890 20 76 61 6c 75 65 20 61 73 20 74 68 65 20 5b 73   value as the [s
158a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
158b0 75 6e 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e  unt()] function.
158c0 0a 2a 2a 20 41 66 74 65 72 20 5b 73 71 6c 69 74  .** After [sqlit
158d0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
158e0 65 74 75 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49  eturned an [SQLI
158f0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
15900 45 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61  E_BUSY], or.** a
15910 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
15920 20 65 72 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72   error code], or
15930 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
15940 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
15950 6e 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20  n .** called on 
15960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
15970 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
15980 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20  tement] for the 
15990 66 69 72 73 74 20 74 69 6d 65 2c 0a 2a 2a 20 74  first time,.** t
159a0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
159b0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74  rns zero..*/.int
159c0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
159d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
159e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
159f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
15a00 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
15a10 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 76 61 6c  .**.** Every val
15a20 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
15a30 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
15a40 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
15a50 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
15a60 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
15a70 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
15a80 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
15a90 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
15aa0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
15ab0 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
15ac0 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
15ad0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
15ae0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
15af0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
15b00 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
15b10 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
15b20 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
15b30 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
15b40 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
15b50 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
15b60 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
15b70 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
15b80 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
15b90 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
15ba0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
15bb0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
15bc0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
15bd0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
15be0 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51  3_TEXT not.** SQ
15bf0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
15c00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
15c10 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
15c20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
15c30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
15c40 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
15c50 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
15c60 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
15c70 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
15c80 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
15c90 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
15ca0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
15cb0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
15cc0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
15cd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15ce0 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20   Results Values 
15cf0 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 0a  From A Query.**.
15d00 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
15d10 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
15d20 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20  tion about.** a 
15d30 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
15d40 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
15d50 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
15d60 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a  ry.  In every.**
15d70 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
15d80 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
15d90 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  inter to the .**
15da0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
15db0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
15dc0 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a  that is being.**
15dd0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
15de0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
15df0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
15e00 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
15e10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
15e20 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
15e30 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a  variants) and.**
15e40 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15e50 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
15e60 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
15e70 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
15e80 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64  ation .** should
15e90 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
15ea0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
15eb0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
15ec0 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20  t set.** has an 
15ed0 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a  index of 0..**.*
15ee0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
15ef0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75  tement is not cu
15f00 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
15f10 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
15f20 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63   if the.** the c
15f30 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
15f40 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
15f50 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
15f60 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20  ined. .** These 
15f70 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
15f80 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
15f90 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
15fa0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
15fb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
15fc0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
15fd0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
15fe0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
15ff0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
16000 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
16010 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73   has been call s
16020 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
16030 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
16040 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
16050 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
16060 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
16070 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
16080 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
16090 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
160a0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
160b0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
160c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
160d0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
160e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
160f0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
16100 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
16110 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
16120 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
16130 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
16140 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
16150 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
16160 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
16170 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
16180 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
16190 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
161a0 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ned.  .**.** The
161b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
161c0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
161d0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
161e0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
161f0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
16200 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
16210 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
16220 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
16230 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
16240 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
16250 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
16260 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
16270 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
16280 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
16290 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
162a0 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
162b0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
162c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
162d0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
162e0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
162f0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
16300 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
16310 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
16320 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
16330 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
16340 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16350 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
16360 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
16370 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
16380 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
16390 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
163a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
163b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
163c0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
163d0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
163e0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
163f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
16400 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
16410 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
16420 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
16430 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65  es() .** routine
16440 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16450 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
16460 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
16470 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
16480 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
16490 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
164a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
164b0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
164c0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
164d0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
164e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
164f0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
16500 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
16510 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
16520 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
16530 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
16540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
16550 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
16560 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
16570 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
16580 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
16590 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
165a0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
165b0 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
165c0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
165d0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
165e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
165f0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
16600 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
16610 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
16620 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
16630 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
16640 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
16650 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
16660 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
16670 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67  rs..**.** String
16680 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
16690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
166a0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
166b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
166c0 0a 2a 2a 20 65 76 65 6e 20 7a 65 72 6f 2d 6c 65  .** even zero-le
166d0 6e 67 74 68 20 73 74 72 69 6e 67 73 2c 20 61 72  ngth strings, ar
166e0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
166f0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72  rminated.  The r
16700 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
16710 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
16720 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
16730 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62  zero-length blob
16740 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
16750 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73  .** pointer, pos
16760 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c  sibly even a NUL
16770 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
16780 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
16790 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f  umn_bytes16() ro
167a0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
167b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
167c0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75  mn_bytes().** bu
167d0 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73  t leaves the res
167e0 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e  ult in UTF-16 in
167f0 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20  stead of UTF-8. 
16800 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65   .** The zero te
16810 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20  rminator is not 
16820 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73  included in this
16830 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68   count..**.** Th
16840 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
16850 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
16860 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
16870 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f  appropriate.  Fo
16880 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
16890 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
168a0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
168b0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
168c0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
168d0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
168e0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
168f0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
16900 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65   to do the conve
16910 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74  rsion.** automat
16920 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
16930 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
16940 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
16950 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  ions that.** are
16960 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
16970 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
16980 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
16990 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
169a0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
169b0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
169c0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
169d0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
169e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
169f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
16a00 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
16a10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
16a20 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
16a30 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
16a40 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
16a50 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
16a60 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
16a70 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
16a80 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
16a90 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
16aa0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
16ab0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
16ac0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
16ad0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
16ae0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
16af0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
16b00 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
16b10 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
16b20 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
16b30 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
16b40 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
16b50 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
16b60 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
16b70 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
16b80 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47  ame as for INTEG
16b90 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
16ba0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
16bb0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
16bc0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
16bd0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
16be0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
16bf0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
16c00 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
16c10 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
16c20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
16c30 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
16c40 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
16c50 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
16c60 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
16c70 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
16c80 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
16c90 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
16ca0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
16cb0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
16cc0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
16cd0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
16ce0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
16cf0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
16d00 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
16d10 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
16d20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
16d30 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
16d40 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
16d50 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
16d60 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
16d70 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
16d80 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
16d90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
16da0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
16db0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
16dc0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
16dd0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
16de0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
16df0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
16e00 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
16e10 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
16e20 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
16e30 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
16e40 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
16e50 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
16e60 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
16e70 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
16e80 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e  It has its.** on
16e90 20 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65   equavalent inte
16ea0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
16eb0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
16ec0 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
16ed0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
16ee0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
16ef0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
16f00 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
16f10 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
16f20 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
16f30 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
16f40 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
16f50 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
16f60 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
16f70 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
16f80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
16f90 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
16fa0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
16fb0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
16fc0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
16fd0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
16fe0 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72   .** Type conver
16ff0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
17000 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
17010 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
17020 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
17030 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
17040 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  >.** <li><p>  Th
17050 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
17060 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
17070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
17080 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ext() .**       
17090 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f     or sqlite3_co
170a0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
170b0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
170c0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
170d0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65  t.**          ne
170e0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
170f0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70  o the string.</p
17100 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ></li>.**.** <li
17110 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
17120 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
17130 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
17140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
17150 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
17160 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
17170 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
17180 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
17190 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
171a0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  erted.**        
171b0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e    to UTF-16.</p>
171c0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
171d0 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
171e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
171f0 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
17200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
17210 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  () or.**        
17220 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
17230 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
17240 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
17250 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
17260 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
17270 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e   UTF-8.</p></li>
17280 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
17290 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
172a0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
172b0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
172c0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
172d0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
172e0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
172f0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
17300 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
17310 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
17320 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
17330 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
17340 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
17350 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
17360 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
17370 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
17380 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
17390 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
173a0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
173b0 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20  metime it is.** 
173c0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
173d0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
173e0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
173f0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  re invalidated. 
17400 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65   .**.** The safe
17410 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
17420 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
17430 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
17440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
17450 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
17460 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
17470 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  *.**  <ul>.**  <
17480 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
17490 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
174a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
174b0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
174c0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
174d0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
174e0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
174f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
17500 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
17510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
17520 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
17530 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
17540 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
17550 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  .**  </ul>.**.**
17560 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
17570 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
17580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17590 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
175a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a  column_blob(),.*
175b0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * or sqlite3_col
175c0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
175d0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
175e0 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20  result into the 
175f0 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61  desired.** forma
17600 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
17610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
17620 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33  tes() or sqlite3
17630 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
17640 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65  ) to.** find the
17650 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
17660 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
17670 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
17680 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
17690 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
176a0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
176b0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
176c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
176d0 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a  ).  And do not.*
176e0 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  * mix calls to s
176f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
17700 78 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c  xt16() with call
17710 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
17720 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
17730 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
17740 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
17750 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
17760 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
17770 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
17780 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
17790 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
177a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
177b0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
177c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
177d0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
177e0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
177f0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
17800 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62  ings.** and blob
17810 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
17820 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
17830 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
17840 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
17850 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
17860 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
17870 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
17880 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
17890 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  to .** [sqlite3_
178a0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  free()]..**.** I
178b0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
178c0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
178d0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
178e0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
178f0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
17900 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
17910 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
17920 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
17930 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
17940 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
17950 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
17960 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
17970 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
17980 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
17990 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
179a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
179b0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
179c0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
179d0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
179e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
179f0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
17a00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
17a10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17a20 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
17a30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
17a40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
17a50 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
17a60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17a70 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
17a80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
17a90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
17aa0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
17ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
17ac0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
17ad0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
17ae0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
17af0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
17b00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
17b10 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
17b20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
17b30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
17b40 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
17b50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
17b60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
17b70 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
17b80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
17b90 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
17ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
17bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
17bc0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
17bd0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
17be0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
17bf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
17c00 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
17c10 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
17c20 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
17c30 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
17c40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
17c50 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
17c60 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
17c70 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 73 71  delete a .** [sq
17c80 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
17c90 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
17ca0 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61  ent]. If the sta
17cb0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78  tement was.** ex
17cc0 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
17cd0 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63  lly, or not exec
17ce0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
17cf0 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  n SQLITE_OK is r
17d00 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65  eturned..** If e
17d10 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
17d20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
17d30 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 53 51   then an .** [SQ
17d40 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
17d50 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c  or code] or [SQL
17d60 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
17d70 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
17d80 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75  code].** is retu
17d90 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69  rned. .**.** Thi
17da0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
17db0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
17dc0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
17dd0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
17de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
17df0 74 20 7c 20 76 69 72 74 75 61 6c 20 6d 61 63 68  t | virtual mach
17e00 69 6e 65 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ine].  If the vi
17e10 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
17e20 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65  s not .** comple
17e30 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
17e40 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
17e50 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
17e60 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
17e70 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
17e80 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74   or an interrupt
17e90 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33  .  (See [sqlite3
17ea0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20  _interrupt()].) 
17eb0 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
17ec0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
17ed0 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
17ee0 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
17ef0 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e  lled,  .** depen
17f00 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
17f10 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
17f20 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  he .** [SQLITE_E
17f30 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f  RROR | result co
17f40 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
17f50 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
17f60 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  RT]..*/.int sqli
17f70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
17f80 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
17f90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17fa0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
17fb0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
17fc0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
17fd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
17fe0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
17ff0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a  ed to reset a .*
18000 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
18010 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  | compiled SQL s
18020 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
18030 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 27  ..** back to it'
18040 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
18050 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
18060 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
18070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
18080 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
18090 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
180a0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
180b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
180c0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
180d0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
180e0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
180f0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
18100 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
18110 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
18120 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a  he bindings..*/.
18130 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
18140 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
18150 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
18160 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
18170 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
18180 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
18190 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
181a0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  o functions are 
181b0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
181c0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
181d0 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f  regates.** or to
181e0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
181f0 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69  havior of existi
18200 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
18210 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
18220 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e   The.** differen
18230 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20  ce only between 
18240 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74 20  the two is that 
18250 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18260 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d  eter, the.** nam
18270 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
18280 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  ) function or ag
18290 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f  gregate, is enco
182a0 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72  ded in UTF-8 for
182b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
182c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
182d0 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c  d UTF-16 for sql
182e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
182f0 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20  tion16()..**.** 
18300 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18310 6e 74 20 69 73 20 74 68 65 20 5b 73 71 6c 69 74  nt is the [sqlit
18320 65 33 20 7c 20 64 61 74 61 62 61 73 65 20 68 61  e3 | database ha
18330 6e 64 6c 65 5d 20 74 68 61 74 20 68 6f 6c 64 73  ndle] that holds
18340 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
18350 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
18360 65 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  e is to be added
18370 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 20 49   or redefined. I
18380 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72  f a single.** pr
18390 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20  ogram uses more 
183a0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
183b0 65 20 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61  e handle interna
183c0 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a  lly, then SQL.**
183d0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
183e0 67 72 65 67 61 74 65 73 20 6d 75 73 74 20 62 65  gregates must be
183f0 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
18400 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74 61  lly to each data
18410 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 77  base.** handle w
18420 69 74 68 20 77 68 69 63 68 20 74 68 65 79 20 77  ith which they w
18430 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  ill be used..**.
18440 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18450 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
18460 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
18470 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
18480 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65  eated.** or rede
18490 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65  fined..** The le
184a0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
184b0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
184c0 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
184d0 69 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a  ive of the .** z
184e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
184f0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
18500 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
18510 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
18520 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
18530 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
18540 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
18550 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
18560 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
18570 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54  sult in an SQLIT
18580 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a  E_ERROR error..*
18590 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70  *.** The third p
185a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
185b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
185c0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
185d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
185e0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
185f0 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
18600 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
18610 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
18620 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
18630 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
18640 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
18650 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
18660 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
18670 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
18680 65 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a  ecifies what .**
18690 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
186a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
186b0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
186c0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
186d0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
186e0 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
186f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
18700 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
18710 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
18720 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
18730 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
18740 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
18750 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
18760 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
18770 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
18780 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
18790 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c  ther.  It is all
187a0 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  owed to.** invok
187b0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
187c0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
187d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
187e0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
187f0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
18800 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
18810 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
18820 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
18830 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68   eTextRep..** Wh
18840 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
18850 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
18860 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
18870 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
18880 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
18890 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
188a0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
188b0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
188c0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
188d0 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
188e0 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
188f0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
18900 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
18910 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  hat.** text enco
18920 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
18930 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
18940 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
18950 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d  .** [SQLITE_ANY]
18960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
18970 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
18980 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
18990 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
189a0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
189b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  he function can 
189c0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
189d0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
189e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73  g.** [sqlite3_us
189f0 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
18a00 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
18a10 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
18a20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
18a30 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
18a40 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
18a50 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
18a60 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
18a70 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
18a80 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
18a90 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  or aggregate. A 
18aa0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
18ab0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
18ac0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
18ad0 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63  f.** the xFunc c
18ae0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
18af0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
18b00 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
18b10 74 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64  the xStep.** and
18b20 20 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65   xFinal paramete
18b30 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
18b40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
18b50 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
18b60 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78  entation.** of x
18b70 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20  Step and xFinal 
18b80 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
18b90 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
18ba0 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
18bb0 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51  n.** existing SQ
18bc0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
18bd0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
18be0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
18bf0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
18c00 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  lback..**.** It 
18c10 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
18c20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
18c30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
18c40 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
18c50 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
18c60 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
18c70 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
18c80 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
18c90 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
18ca0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 72  or differing per
18cb0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
18cc0 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
18cd0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
18ce0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f  mplementation mo
18cf0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
18d00 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
18d10 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
18d20 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
18d30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18d40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
18d50 0a 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20  .  sqlite3 *,.  
18d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
18d70 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
18d80 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
18d90 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a  xtRep,.  void*,.
18da0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
18db0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
18dc0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
18dd0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
18de0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
18df0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
18e00 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
18e10 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
18e20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
18e30 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
18e40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
18e50 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  6(.  sqlite3*,. 
18e60 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
18e70 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
18e80 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
18e90 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c  extRep,.  void*,
18ea0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
18eb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
18ec0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
18ed0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
18ee0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
18ef0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
18f00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
18f10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
18f20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
18f30 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
18f40 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
18f50 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
18f60 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
18f70 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
18f80 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
18f90 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
18fa0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
18fb0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
18fc0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18fd0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
18fe0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
18ff0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
19000 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
19010 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
19020 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
19030 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
19040 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
19050 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
19060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19070 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
19080 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
19090 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
190a0 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
190b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
190c0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
190d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
190e0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
190f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19100 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69   Obsolete Functi
19110 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
19120 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  functions are al
19130 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20  l now obsolete. 
19140 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
19150 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
19160 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
19170 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
19180 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f  , we continue to
19190 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73   support.** thes
191a0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f  e functions.  Ho
191b0 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c  wever, new devel
191c0 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20  opment projects 
191d0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
191e0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
191f0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
19200 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
19210 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
19220 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
19230 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
19240 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
19250 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20  l you want they 
19260 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  do..*/.int sqlit
19270 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
19280 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
19290 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  xt*);.int sqlite
192a0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
192b0 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
192c0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
192d0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
192e0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
192f0 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tmt*);.int sqlit
19300 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
19310 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71  r(void);.void sq
19320 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
19330 61 6e 75 70 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  anup(void);../*.
19340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
19350 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
19360 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
19370 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
19380 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
19390 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
193a0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
193b0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
193c0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
193d0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
193e0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
193f0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
19400 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
19410 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
19420 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
19430 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
19440 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
19450 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
19460 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
19470 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
19480 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
19490 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
194a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
194b0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
194c0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
194d0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
194e0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
194f0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
19500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19510 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
19520 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
19530 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ters to.** [sqli
19540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
19550 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
19560 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
19570 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
19580 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
19590 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
195a0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
195b0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
195c0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
195d0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
195e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
195f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
19600 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
19610 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
19620 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73  esponding .** [s
19630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
19640 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ob | sqlite3_col
19650 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20  umn_* routines] 
19660 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20  except that .** 
19670 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
19680 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71  ake a single [sq
19690 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f  lite3_value*] po
196a0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
196b0 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
196c0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
196d0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
196e0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
196f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
19700 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
19710 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
19720 20 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a   a UTF16 string.
19730 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
19740 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
19750 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
19760 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
19770 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
19780 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
19790 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
197a0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
197b0 72 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e  ract UTF16 strin
197c0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
197d0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
197e0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
197f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19800 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
19810 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
19820 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
19830 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
19840 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
19850 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
19860 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
19870 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
19880 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
19890 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
198a0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
198b0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
198c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
198d0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
198e0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
198f0 69 6f 6e 20 28 69 6e 20 6f 72 64 65 72 0a 2a 2a  ion (in order.**
19900 20 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61   words if the va
19910 6c 75 65 20 69 73 20 6f 72 69 67 69 6e 61 6c 20  lue is original 
19920 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
19930 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
19940 72 29 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  r).** then it is
19950 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73   done.  Otherwis
19960 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
19970 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a  occurs.  The .**
19980 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
19990 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
199a0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
199b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
199c0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
199d0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
199e0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
199f0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  t the pointer th
19a00 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  at.** is returne
19a10 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
19a20 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
19a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
19a40 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
19a50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
19a60 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
19a70 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
19a80 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
19a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
19aa0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
19ab0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
19ac0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
19ad0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
19ae0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
19af0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20  alue_text16()]. 
19b00 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f   .**.** These ro
19b10 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
19b20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
19b30 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
19b40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19b50 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
19b60 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
19b70 65 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  e* parameters..*
19b80 2a 20 4f 72 2c 20 69 66 20 74 68 65 20 73 71 6c  * Or, if the sql
19b90 69 74 65 33 5f 76 61 6c 75 65 2a 20 61 72 67 75  ite3_value* argu
19ba0 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 20  ment comes from 
19bb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
19bc0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a 2a 20  umn_value()].** 
19bd0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 6e 20  interface, then 
19be0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73  these routines s
19bf0 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20  hould be called 
19c00 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
19c10 72 65 61 64 0a 2a 2a 20 74 68 61 74 20 72 61 6e  read.** that ran
19c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
19c30 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  _value()]..*/.co
19c40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
19c50 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
19c60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
19c70 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
19c80 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
19c90 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
19ca0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
19cb0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
19cc0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
19cd0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
19ce0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19cf0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19d00 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
19d10 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
19d20 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
19d30 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
19d40 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
19d50 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
19d60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
19d70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
19d80 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
19d90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
19da0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
19db0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
19dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
19dd0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
19de0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
19df0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
19e00 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
19e10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
19e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
19e30 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
19e40 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
19e50 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
19e60 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
19e70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19e80 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
19e90 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
19ea0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
19eb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
19ec0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
19ed0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
19ee0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
19ef0 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
19f00 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
19f10 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 20  ng their state. 
19f20 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
19f30 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
19f40 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20  is called for a 
19f50 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
19f60 67 61 74 65 2c 20 61 20 6e 65 77 20 73 74 72 75  gate, a new stru
19f70 63 74 75 72 65 20 6f 66 20 73 69 7a 65 20 6e 42  cture of size nB
19f80 79 74 65 73 0a 2a 2a 20 69 73 20 61 6c 6c 6f 63  ytes.** is alloc
19f90 61 74 65 64 2c 20 7a 65 72 6f 65 64 2c 20 61 6e  ated, zeroed, an
19fa0 64 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 6e 20  d returned.  On 
19fb0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
19fc0 20 28 66 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d   (for the.** sam
19fd0 65 20 61 67 67 72 65 67 61 74 65 20 69 6e 73 74  e aggregate inst
19fe0 61 6e 63 65 29 20 74 68 65 20 73 61 6d 65 20 62  ance) the same b
19ff0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
1a000 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  d.  The implemen
1a010 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
1a020 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
1a030 73 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  se the returned 
1a040 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
1a050 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
1a060 20 54 68 65 20 62 75 66 66 65 72 20 61 6c 6c 6f   The buffer allo
1a070 63 61 74 65 64 20 69 73 20 66 72 65 65 64 20 61  cated is freed a
1a080 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1a090 53 51 4c 69 74 65 20 77 68 61 6e 20 74 68 65 20  SQLite whan the 
1a0a0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65  aggregate.** que
1a0b0 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
1a0c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
1a0d0 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
1a0e0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
1a0f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
1a100 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
1a110 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
1a120 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
1a130 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1a140 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  he callback rout
1a150 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
1a160 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
1a170 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
1a180 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1a190 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
1a1a0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
1a1b0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
1a1c0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
1a1d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
1a1e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
1a1f0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
1a200 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
1a210 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
1a220 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
1a230 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
1a240 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
1a250 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 55  ons.**.** The pU
1a260 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
1a270 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1a280 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1a290 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
1a2a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1a2b0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
1a2c0 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 72 65  es.** used to re
1a2d0 67 69 73 74 65 72 20 75 73 65 72 20 66 75 6e 63  gister user func
1a2e0 74 69 6f 6e 73 20 69 73 20 61 76 61 69 6c 61 62  tions is availab
1a2f0 6c 65 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70  le to.** the imp
1a300 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1a310 68 65 20 66 75 6e 63 74 69 6f 6e 20 75 73 69 6e  he function usin
1a320 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 0a  g this call..**.
1a330 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1a340 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
1a350 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
1a360 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
1a370 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1a380 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
1a390 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
1a3a0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
1a3b0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
1a3c0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
1a3d0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
1a3e0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
1a3f0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
1a400 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
1a410 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
1a420 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
1a430 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64  associate meta-d
1a440 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
1a450 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
1a460 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
1a470 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
1a480 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
1a490 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
1a4a0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
1a4b0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
1a4c0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
1a4d0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
1a4e0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
1a4f0 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  a-data may be pr
1a500 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
1a510 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
1a520 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
1a530 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
1a540 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
1a550 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
1a560 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
1a570 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
1a580 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
1a590 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
1a5a0 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73  ** meta-data ass
1a5b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1a5c0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
1a5d0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
1a5e0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
1a5f0 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
1a600 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
1a610 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
1a620 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
1a630 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
1a640 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
1a650 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
1a660 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
1a670 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
1a680 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1a690 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
1a6a0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
1a6b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a6c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1a6d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1a6e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1a6f0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a  the meta-data.**
1a700 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1a710 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
1a720 74 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 63  t value to the c
1a730 75 72 72 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  urrent SQL funct
1a740 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c 20 77 68 65  ion.** call, whe
1a750 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1a760 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  nd parameter. If
1a770 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20 68 61   no meta-data ha
1a780 73 20 62 65 65 6e 20 73 65 74 20 66 6f 72 0a 2a  s been set for.*
1a790 2a 20 74 68 61 74 20 76 61 6c 75 65 2c 20 74 68  * that value, th
1a7a0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
1a7b0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1a7c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a7d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
1a7e0 73 20 75 73 65 64 20 74 6f 20 61 73 73 6f 63 69  s used to associ
1a7f0 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69  ate meta-data wi
1a800 74 68 20 61 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e  th an SQL.** fun
1a810 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 20  ction argument. 
1a820 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1a830 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1a840 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74   to the meta-dat
1a850 61 0a 2a 2a 20 74 6f 20 62 65 20 61 73 73 6f 63  a.** to be assoc
1a860 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e  iated with the N
1a870 74 68 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e  th user function
1a880 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 2e   argument value.
1a890 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70   The fourth.** p
1a8a0 61 72 61 6d 65 74 65 72 20 73 70 65 63 69 66 69  arameter specifi
1a8b0 65 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  es a destructor 
1a8c0 74 68 61 74 20 77 69 6c 6c 20 62 65 20 63 61 6c  that will be cal
1a8d0 6c 65 64 20 6f 6e 20 74 68 65 20 6d 65 74 61 2d  led on the meta-
1a8e0 0a 2a 2a 20 64 61 74 61 20 70 6f 69 6e 74 65 72  .** data pointer
1a8f0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 20 77   to release it w
1a900 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1a910 67 65 72 20 72 65 71 75 69 72 65 64 2e 20 49 66  ger required. If
1a920 20 74 68 65 20 0a 2a 2a 20 64 65 73 74 72 75 63   the .** destruc
1a930 74 6f 72 20 69 73 20 4e 55 4c 4c 2c 20 69 74 20  tor is NULL, it 
1a940 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 2e 0a  is not invoked..
1a950 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63  **.** In practic
1a960 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20  e, meta-data is 
1a970 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
1a980 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
1a990 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
1a9a0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
1a9b0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
1a9c0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
1a9d0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
1a9e0 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
1a9f0 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
1aa00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
1aa10 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
1aa20 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
1aa30 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
1aa40 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1aa50 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
1aa60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
1aa70 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
1aa80 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
1aa90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
1aaa0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
1aab0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 2c  3_context*, int,
1aac0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
1aad0 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
1aae0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
1aaf0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
1ab00 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
1ab10 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
1ab20 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
1ab30 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  al value for the
1ab40 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
1ab50 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
1ab60 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
1ab70 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
1ab80 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
1ab90 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
1aba0 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63    If the destruc
1abb0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
1abc0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
1abd0 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
1abe0 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
1abf0 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
1ac00 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
1ac10 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
1ac20 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1ac30 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68  e destroyed.  Th
1ac40 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  e .** SQLITE_TRA
1ac50 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
1ac60 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
1ac70 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
1ac80 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
1ac90 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
1aca0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
1acb0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
1acc0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
1acd0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
1ace0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
1acf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
1ad00 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
1ad10 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
1ad20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
1ad30 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
1ad40 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
1ad50 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
1ad60 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
1ad70 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
1ad80 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
1ad90 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
1ada0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
1adb0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
1adc0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
1add0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
1ade0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
1adf0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
1ae00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1ae10 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
1ae20 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
1ae30 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
1ae40 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1ae50 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
1ae60 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
1ae70 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
1ae80 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
1ae90 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
1aea0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
1aeb0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1aec0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1aed0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1aee0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
1aef0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
1af00 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
1af10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
1af20 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
1af30 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  e the .** [sqlit
1af40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
1af50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66  qlite3_bind_*] f
1af60 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1af70 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69  ns used.** to bi
1af80 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
1af90 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
1afa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1afb0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
1afc0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1afd0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
1afe0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75  ite3_bind_* docu
1aff0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a  mentation] for.*
1b000 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
1b010 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1b020 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
1b030 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
1b040 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b050 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
1b060 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
1b070 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
1b080 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
1b090 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 20 20   an exception.  
1b0a0 54 68 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  The.** parameter
1b0b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
1b0c0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
1b0d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1b0e0 6f 72 31 36 28 29 0a 2a 2a 20 69 73 20 74 68 65  or16().** is the
1b0f0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
1b100 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1b110 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
1b120 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 63 61 75  ult_toobig() cau
1b130 73 65 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  se the function 
1b140 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1b150 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 64 20 65  * to throw and e
1b160 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
1b170 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
1b180 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67   BLOB is to long
1b190 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74  .** to represent
1b1a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1b1b0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1b1c0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
1b1d0 6e 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  n the same threa
1b1e0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
1b1f0 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
1b200 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71  ted with the [sq
1b210 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
1b220 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 76 6f 69 64 20  ointer..*/.void 
1b230 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
1b240 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
1b250 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
1b260 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
1b270 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
1b280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
1b290 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
1b2a0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
1b2b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b2c0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
1b2d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
1b2e0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
1b2f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b300 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
1b310 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1b320 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
1b330 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b340 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
1b350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b360 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b370 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
1b380 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
1b390 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
1b3a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
1b3b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1b3c0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1b3d0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
1b3e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b3f0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
1b400 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1b410 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
1b420 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
1b430 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b440 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
1b450 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
1b460 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
1b470 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
1b480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1b490 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
1b4a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
1b4b0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
1b4c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
1b4d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1b4e0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
1b4f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
1b500 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
1b510 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
1b520 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b530 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
1b540 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1b550 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
1b560 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
1b570 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b580 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
1b590 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
1b5a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
1b5b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
1b5c0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
1b5d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
1b5e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b5f0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
1b600 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
1b610 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
1b620 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
1b630 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
1b640 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1b650 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  to the.** [sqlit
1b660 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63  e3*] handle spec
1b670 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
1b680 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a  st argument. .**
1b690 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
1b6a0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
1b6b0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
1b6c0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
1b6d0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
1b6e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1b6f0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
1b700 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1b710 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
1b720 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
1b730 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
1b740 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1b750 6e 31 36 28 29 2e 20 20 49 6e 20 61 6c 6c 20 63  n16().  In all c
1b760 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
1b770 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
1b780 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
1b790 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
1b7a0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1b7b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 6f 6e 65  ment must be one
1b7c0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
1b7d0 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
1b7e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
1b7f0 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  6LE] or [SQLITE_
1b800 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61  UTF16BE], indica
1b810 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73  ting that the us
1b820 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72  er-supplied.** r
1b830 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74  outine expects t
1b840 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e  o be passed poin
1b850 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
1b860 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
1b870 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  F-8,.** UTF-16 l
1b880 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20  ittle-endian or 
1b890 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
1b8a0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
1b8b0 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
1b8c0 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70  to the user supp
1b8d0 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73  lied routine mus
1b8e0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
1b8f0 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75  he fifth.** argu
1b900 6d 65 6e 74 2e 20 49 66 20 69 74 20 69 73 20 4e  ment. If it is N
1b910 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
1b920 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
1b930 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
1b940 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
1b950 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
1b960 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
1b970 72 65 29 2e 20 45 61 63 68 20 74 69 6d 65 20 74  re). Each time t
1b980 68 65 20 75 73 65 72 0a 2a 2a 20 73 75 70 70 6c  he user.** suppl
1b990 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
1b9a0 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
1b9b0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
1b9c0 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64  the void* passed
1b9d0 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74   as.** the fourt
1b9e0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1b9f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1ba00 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73  lation() or.** s
1ba10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1ba20 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69  llation16() as i
1ba30 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
1ba40 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  er..**.** The re
1ba50 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
1ba60 73 20 74 6f 20 74 68 65 20 75 73 65 72 2d 73 75  s to the user-su
1ba70 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
1ba80 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
1ba90 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
1baa0 74 65 64 20 62 79 20 61 20 5b 6c 65 6e 67 74 68  ted by a [length
1bab0 2c 20 64 61 74 61 5d 20 70 61 69 72 20 61 6e 64  , data] pair and
1bac0 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
1bad0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
1bae0 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
1baf0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1bb00 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
1bb10 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
1bb20 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
1bb30 20 54 68 65 20 75 73 65 72 20 72 6f 75 74 69 6e   The user routin
1bb40 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
1bb50 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f  negative, zero o
1bb60 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a  r positive if.**
1bb70 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
1bb80 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
1bb90 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
1bba0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
1bbb0 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20  cond.** string. 
1bbc0 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
1bbd0 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
1bbe0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
1bbf0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1bc00 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
1bc10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1bc20 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70  ation().** excap
1bc30 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
1bc40 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
1bc50 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
1bc60 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
1bc70 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
1bc80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
1bc90 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
1bca0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
1bcb0 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
1bcc0 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
1bcd0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
1bce0 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
1bcf0 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
1bd00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1bd10 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 20 20  ollation_v2().  
1bd20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
1bd30 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a  estroyed when.**
1bd40 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
1bd50 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
1bd60 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
1bd70 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
1bd80 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68  nctions.** or wh
1bd90 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  en the [sqlite3*
1bda0 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
1bdb0 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  e is closed usin
1bdc0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
1bdd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
1bde0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1bdf0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 69 6e 74  llation_v2() int
1be00 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
1be10 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 73 75  mental and.** su
1be20 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1be30 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1be40 65 73 2e 20 20 54 68 65 20 6f 74 68 65 72 20 63  es.  The other c
1be50 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
1be60 6e 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 61  n.** functions a
1be70 72 65 20 73 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e  re stable..*/.in
1be80 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
1be90 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
1bea0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
1beb0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
1bec0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
1bed0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
1bee0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
1bef0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
1bf00 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
1bf10 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1bf20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1bf30 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
1bf40 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
1bf50 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
1bf60 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
1bf70 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
1bf80 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
1bf90 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
1bfa0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
1bfb0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
1bfc0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
1bfd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1bfe0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
1bff0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
1c000 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
1c010 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
1c020 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
1c030 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
1c040 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
1c050 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
1c060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c070 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
1c080 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1c090 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
1c0a0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
1c0b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1c0c0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
1c0d0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
1c0e0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
1c0f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c100 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
1c110 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
1c120 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
1c130 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  to be called whe
1c140 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
1c150 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
1c160 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75  uence is.** requ
1c170 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ired..**.** If t
1c180 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
1c190 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
1c1a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
1c1b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
1c1c0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
1c1d0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
1c1e0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
1c1f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1c200 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
1c210 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
1c220 2d 38 2e 20 49 66 20 73 71 6c 69 74 65 33 5f 63  -8. If sqlite3_c
1c230 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
1c240 36 28 29 20 69 73 20 75 73 65 64 2c 20 74 68 65  6() is used, the
1c250 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61   names.** are pa
1c260 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
1c270 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
1c280 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20 63   byte order. A c
1c290 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  all to either.**
1c2a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
1c2b0 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20  es any existing 
1c2c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
1c2d0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1c2e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
1c2f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1c300 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
1c310 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
1c320 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
1c330 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1c340 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
1c350 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1c360 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 54 68  n_needed16(). Th
1c370 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1c380 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
1c390 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 54 68 65  e.** handle. The
1c3a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1c3b0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
1c3c0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
1c3d0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a  _UTF16BE], or.**
1c3e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
1c3f0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
1c400 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
1c410 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
1c420 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
1c430 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
1c440 69 72 65 64 2e 20 54 68 65 20 66 6f 75 72 74 68  ired. The fourth
1c450 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1c460 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1c470 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
1c480 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a  ion sequence..**
1c490 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
1c4a0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
1c4b0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
1c4c0 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
1c4d0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1c4e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1c4f0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
1c500 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1c510 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
1c520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1c530 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
1c540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
1c550 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
1c560 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
1c570 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
1c580 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
1c590 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
1c5a0 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
1c5b0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1c5c0 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
1c5d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
1c5e0 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
1c5f0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
1c600 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
1c610 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  id*).);../*.** S
1c620 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
1c630 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
1c640 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
1c650 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
1c660 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
1c670 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
1c680 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
1c690 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
1c6a0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
1c6b0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
1c6c0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
1c6d0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
1c6e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c6f0 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
1c700 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1c710 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1c720 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
1c730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1c740 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
1c750 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
1c760 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
1c770 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
1c780 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
1c790 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
1c7a0 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
1c7b0 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
1c7c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
1c7d0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
1c7e0 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
1c7f0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
1c800 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
1c810 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
1c820 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
1c830 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
1c840 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
1c850 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
1c860 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
1c870 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
1c880 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
1c890 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
1c8a0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1c8b0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
1c8c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
1c8d0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
1c8e0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
1c8f0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1c900 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e 64  PI3REF:  Suspend
1c910 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
1c920 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
1c930 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
1c940 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
1c950 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
1c960 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
1c970 2a 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  * a number of mi
1c980 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
1c990 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
1c9a0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
1c9b0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1c9c0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
1c9d0 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
1c9e0 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69  ests with .** mi
1c9f0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
1ca00 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
1ca10 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
1ca20 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 0a   rounded up to .
1ca30 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
1ca40 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
1ca50 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
1ca60 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
1ca70 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65  lly .** requeste
1ca80 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
1ca90 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
1caa0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
1cab0 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
1cac0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1cad0 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
1cae0 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
1caf0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
1cb00 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1cb10 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  bject..*/.int sq
1cb20 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
1cb30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cb40 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  F:  Name Of The 
1cb50 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
1cb60 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
1cb70 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
1cb80 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
1cb90 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
1cba0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
1cbb0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
1cbc0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61  f a folder (a.ka
1cbd0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
1cbe0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
1cbf0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
1cc00 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c  d by SQLite will
1cc10 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
1cc20 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49  at directory.  I
1cc30 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
1cc40 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** is NULL point
1cc50 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
1cc60 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f  does a search fo
1cc70 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
1cc80 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69   temporary.** fi
1cc90 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
1cca0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1ccb0 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69  fe to modify thi
1ccc0 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20  s variable once 
1ccd0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1cce0 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65  ction.** has bee
1ccf0 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73  n opened.  It is
1cd00 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
1cd10 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
1cd20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
1cd30 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
1cd40 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
1cd50 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
1cd60 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
1cd70 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
1cd80 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d  een call and rem
1cd90 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68  ain unchanged th
1cda0 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c  ereafter..*/.SQL
1cdb0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
1cdc0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
1cdd0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
1cde0 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74 20  CAPI3REF:  Test 
1cdf0 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44 61  To See If The Da
1ce00 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75 74  tabase Is In Aut
1ce10 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
1ce20 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73 65 65 20  .** Test to see 
1ce30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1ce40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ce50 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74  ection is in aut
1ce60 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f 64 65 2e  ocommit.** mode.
1ce70 20 20 52 65 74 75 72 6e 20 54 52 55 45 20 69 66    Return TRUE if
1ce80 20 69 74 20 69 73 20 61 6e 64 20 46 41 4c 53 45   it is and FALSE
1ce90 20 69 66 20 6e 6f 74 2e 20 20 41 75 74 6f 63 6f   if not.  Autoco
1cea0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a  mmit mode is on.
1ceb0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ** by default.  
1cec0 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73 20 64 69  Autocommit is di
1ced0 73 61 62 6c 65 64 20 62 79 20 61 20 42 45 47 49  sabled by a BEGI
1cee0 4e 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  N statement and 
1cef0 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20 62 79 20  reenabled.** by 
1cf00 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d 49 54 20  the next COMMIT 
1cf10 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a  or ROLLBACK..**.
1cf20 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
1cf30 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
1cf40 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
1cf50 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
1cf60 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
1cf70 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
1cf80 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
1cf90 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
1cfa0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
1cfb0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
1cfc0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
1cfd0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
1cfe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cff0 20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62    Find The Datab
1d000 61 73 65 20 48 61 6e 64 6c 65 20 41 73 73 6f 63  ase Handle Assoc
1d010 69 61 74 65 64 20 57 69 74 68 20 41 20 50 72 65  iated With A Pre
1d020 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
1d030 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
1d040 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
1d050 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77  base handle to w
1d060 68 69 63 68 20 61 0a 2a 2a 20 5b 73 71 6c 69 74  hich a.** [sqlit
1d070 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
1d080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
1d090 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 69 73 20 69  longs..** This i
1d0a0 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  s the same datab
1d0b0 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20  ase handle that 
1d0c0 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  was.** the first
1d0d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1d0e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d0f0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
1d100 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20  ariants.** that 
1d110 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65 61  was used to crea
1d120 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
1d130 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
1d140 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
1d150 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
1d160 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1d170 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
1d180 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
1d190 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
1d1a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1d1b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d1c0 69 6e 65 73 0a 2a 2a 20 72 65 67 69 73 74 65 72  ines.** register
1d1d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d1e0 6f 6e 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ons to be invoke
1d1f0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
1d200 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 63  nsaction.** is c
1d210 6f 6d 6d 69 74 74 65 64 20 6f 72 20 72 6f 6c 6c  ommitted or roll
1d220 65 64 20 62 61 63 6b 2e 20 20 54 68 65 20 70 41  ed back.  The pA
1d230 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
1d240 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
1d250 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1d260 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  .  If the callba
1d270 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
1d280 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a  ook function .**
1d290 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1d2a0 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  o, then the comm
1d2b0 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
1d2c0 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
1d2d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
1d2e0 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
1d2f0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
1d300 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76  ered, its pArg v
1d310 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
1d320 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e  ..** Otherwise N
1d330 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
1d340 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69  .**.** Registeri
1d350 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
1d360 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
1d370 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
1d380 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
1d390 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
1d3a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
1d3b0 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
1d3c0 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b   .** rolled back
1d3d0 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
1d3e0 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
1d3f0 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
1d400 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
1d410 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
1d420 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
1d430 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
1d440 63 75 72 2e 20 54 68 65 20 0a 2a 2a 20 63 61 6c  cur. The .** cal
1d450 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
1d460 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
1d470 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
1d480 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 0a 2a 2a  ically rolled.**
1d490 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
1d4a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d4b0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1d4c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
1d4d0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
1d4e0 74 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65  terfaces and are
1d4f0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1d500 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ge..*/.void *sql
1d510 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
1d520 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
1d530 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1d540 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1d550 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
1d560 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
1d570 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
1d580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d590 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
1d5a0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
1d5b0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  acks.**.** Regis
1d5c0 74 65 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ter a callback f
1d5d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
1d5e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d5f0 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20  tion identified 
1d600 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74  by the .** first
1d610 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20   argument to be 
1d620 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
1d630 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65   a row is update
1d640 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
1d650 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  eleted..** Any c
1d660 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
1d670 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
1d680 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
1d690 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a  for the same .**
1d6a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d6b0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
1d6c0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  en..**.** The se
1d6d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1d6e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1d6f0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
1d700 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20  voke when a .** 
1d710 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
1d720 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
1d730 74 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ted. The first a
1d740 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
1d750 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20  allback is.** a 
1d760 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1d770 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1d780 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
1d790 6b 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  k(). The second 
1d7a0 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67  callback .** arg
1d7b0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
1d7c0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 2c 20 53  SQLITE_INSERT, S
1d7d0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 6f 72 20  QLITE_DELETE or 
1d7e0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 2c 20 64  SQLITE_UPDATE, d
1d7f0 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 74  epending.** on t
1d800 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
1d810 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
1d820 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f  lback to be invo
1d830 6b 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ked. The third a
1d840 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72  nd .** fourth ar
1d850 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
1d860 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
1d870 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
1d880 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a  database and .**
1d890 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
1d8a0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
1d8b0 74 65 64 20 72 6f 77 2e 20 54 68 65 20 66 69 6e  ted row. The fin
1d8c0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
1d8d0 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65  meter is .** the
1d8e0 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
1d8f0 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  w. In the case o
1d900 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
1d910 73 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61  s is the rowid a
1d920 66 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64  fter .** the upd
1d930 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
1d940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
1d950 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
1d960 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
1d970 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
1d980 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
1d990 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
1d9a0 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
1d9b0 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
1d9c0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
1d9d0 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
1d9e0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
1d9f0 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 20   its pArg value 
1da00 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
1da10 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
1da20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 76  s returned..*/.v
1da30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64  oid *sqlite3_upd
1da40 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69  ate_hook(.  sqli
1da50 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  te3*, .  void(*)
1da60 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61  (void *,int ,cha
1da70 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63  r const *,char c
1da80 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69  onst *,sqlite3_i
1da90 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29  nt64),.  void*.)
1daa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dab0 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  F:  Enable Or Di
1dac0 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
1dad0 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 54  er Cache.**.** T
1dae0 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
1daf0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
1db00 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
1db10 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
1db20 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
1db30 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1db40 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69  between connecti
1db50 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ons to the same 
1db60 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61  database..** Sha
1db70 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
1db80 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
1db90 69 73 20 74 72 75 65 20 61 6e 64 20 64 69 73 61  is true and disa
1dba0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
1dbb0 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65  ment.** is false
1dbc0 2e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e  ..**.** Beginnin
1dbd0 67 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  g in SQLite vers
1dbe0 69 6f 6e 20 33 2e 35 2e 30 2c 20 63 61 63 68 65  ion 3.5.0, cache
1dbf0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
1dc00 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
1dc10 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  .** for an entir
1dc20 65 20 70 72 6f 63 65 73 73 2e 20 20 49 6e 20 70  e process.  In p
1dc30 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
1dc40 20 53 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67   SQLite, sharing
1dc50 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20   was.** enabled 
1dc60 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
1dc70 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
1dc80 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
1dc90 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
1dca0 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
1dcb0 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
1dcc0 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
1dcd0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
1dce0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1dcf0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1dd00 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1dd10 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
1dd20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
1dd30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
1dd40 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
1dd50 68 61 72 69 6e 67 20 6d 6f 64 65 20 74 68 61 74  haring mode that
1dd60 20 77 61 73 0a 2a 2a 20 69 6e 20 65 66 66 65 63   was.** in effec
1dd70 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
1dd80 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a  ey were opened..
1dd90 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
1dda0 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75  bles cannot be u
1ddb0 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65  sed with a share
1ddc0 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73  d cache.  When s
1ddd0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
1dde0 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b  s enabled, the [
1ddf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
1de00 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65  odule()] API use
1de10 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  d to register.**
1de20 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
1de30 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
1de40 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  rn an error..**.
1de50 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1de60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1de70 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
1de80 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c  che was.** enabl
1de90 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73  ed or disabled s
1dea0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
1deb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
1dec0 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20   error code].** 
1ded0 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
1dee0 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61  rwise..**.** Sha
1def0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
1df00 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1df10 2e 20 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  .  But this migh
1df20 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
1df30 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
1df40 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
1df50 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
1df60 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
1df70 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
1df80 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
1df90 70 6c 69 63 69 74 6c 79 2e 0a 2a 2f 0a 69 6e 74  plicitly..*/.int
1dfa0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
1dfb0 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
1dfc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dfd0 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20  EF:  Attempt To 
1dfe0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
1dff0 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74  .**.** Attempt t
1e000 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f  o free N bytes o
1e010 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
1e020 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
1e030 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d  n-essential.** m
1e040 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e050 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  s held by the da
1e060 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 20 28  tabase library (
1e070 65 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 20  example: memory 
1e080 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63 68  .** used to cach
1e090 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73  e database pages
1e0a0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
1e0b0 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2f 0a 69 6e 74  ormance)..*/.int
1e0c0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
1e0d0 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
1e0e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1e0f0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
1e100 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
1e110 2a 20 50 6c 61 63 65 20 61 20 22 73 6f 66 74 22  * Place a "soft"
1e120 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
1e130 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
1e140 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
1e150 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20  allocated.** by 
1e160 53 51 4c 69 74 65 2e 20 20 49 66 20 61 6e 20 69  SQLite.  If an i
1e170 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
1e180 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
1e190 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65  .** that would e
1e1a0 78 63 65 65 64 20 74 68 65 20 73 70 65 63 69 66  xceed the specif
1e1b0 69 65 64 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  ied limit, [sqli
1e1c0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
1e1d0 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f  ry()] is.** invo
1e1e0 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ked one or more 
1e1f0 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
1e200 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
1e210 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
1e220 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a  n.** is made..**
1e230 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73  .** The limit is
1e240 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20   called "soft", 
1e250 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69  because if [sqli
1e260 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
1e270 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ry()] cannot.** 
1e280 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20  free sufficient 
1e290 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e  memory to preven
1e2a0 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d  t the limit from
1e2b0 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c   being exceeded,
1e2c0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  .** the memory i
1e2d0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77  s allocated anyw
1e2e0 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65  ay and the curre
1e2f0 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  nt operation pro
1e300 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e  ceeds..**.** A n
1e310 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20  egative or zero 
1e320 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e  value for N mean
1e330 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
1e340 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  no soft heap lim
1e350 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  it and.** [sqlit
1e360 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
1e370 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
1e380 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65  e called when me
1e390 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65  mory is exhauste
1e3a0 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
1e3b0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
1e3c0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
1e3d0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  is zero..**.** S
1e3e0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65  QLite makes a be
1e3f0 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e  st effort to hon
1e400 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
1e410 20 6c 69 6d 69 74 2e 20 20 42 75 74 20 69 66 20   limit.  But if 
1e420 69 74 0a 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20  it.** is unable 
1e430 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79  to reduce memory
1e440 20 75 73 61 67 65 20 62 65 6c 6f 77 20 74 68 65   usage below the
1e450 20 73 6f 66 74 20 6c 69 6d 69 74 2c 20 65 78 65   soft limit, exe
1e460 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63  cution will.** c
1e470 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20  ontinue without 
1e480 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63  error or notific
1e490 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20  ation.  This is 
1e4a0 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73  why the limit is
1e4b0 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73   .** called a "s
1e4c0 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20  oft" limit.  It 
1e4d0 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
1e4e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f 66 74  ..**.** The soft
1e4f0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 69   heap limit is i
1e500 6d 70 6c 65 6d 65 6e 74 65 64 20 75 73 69 6e 67  mplemented using
1e510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
1e520 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a  mory_alarm()].**
1e530 20 69 6e 74 65 72 66 61 63 65 2e 20 20 4f 6e 6c   interface.  Onl
1e540 79 20 61 20 73 69 6e 67 6c 65 20 6d 65 6d 6f 72  y a single memor
1e550 79 20 61 6c 61 72 6d 20 69 73 20 61 76 61 69 6c  y alarm is avail
1e560 61 62 6c 65 20 69 6e 20 74 68 65 20 64 65 66 61  able in the defa
1e570 75 6c 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ult.** implement
1e580 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 6d 65 61  ation.  This mea
1e590 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 61  ns that if the a
1e5a0 70 70 6c 69 63 61 74 69 6f 6e 20 61 6c 73 6f 20  pplication also 
1e5b0 75 73 65 73 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f  uses the.** memo
1e5c0 72 79 20 61 6c 61 72 6d 20 69 6e 74 65 72 66 61  ry alarm interfa
1e5d0 63 65 20 69 74 20 77 69 6c 6c 20 69 6e 74 65 72  ce it will inter
1e5e0 66 65 72 65 20 77 69 74 68 20 74 68 65 20 6f 70  fere with the op
1e5f0 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  eration of the.*
1e600 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  * soft heap limi
1e610 74 20 61 6e 64 20 75 6e 64 65 66 69 6e 65 64 20  t and undefined 
1e620 62 65 68 61 76 69 6f 72 20 77 69 6c 6c 20 72 65  behavior will re
1e630 73 75 6c 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 50 72  sult.  .**.** Pr
1e640 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1e650 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
1e660 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
1e670 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
1e680 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
1e690 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
1e6a0 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
1e6b0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
1e6c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
1e6d0 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
1e6e0 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
1e6f0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
1e700 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
1e710 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
1e720 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20  o all threads.  
1e730 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
1e740 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
1e750 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
1e760 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
1e770 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
1e780 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e790 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
1e7a0 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20    In.** version 
1e7b0 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e  3.5.0 there is n
1e7c0 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20  o mechanism for 
1e7d0 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61  limiting the hea
1e7e0 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69  p usage for.** i
1e7f0 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64  ndividual thread
1e800 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1e810 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
1e820 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  it(int);../*.** 
1e830 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61  CAPI3REF:  Extra
1e840 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
1e850 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
1e860 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Table.**.** This
1e870 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75   routine.** retu
1e880 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62  rns meta-data ab
1e890 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
1e8a0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
1e8b0 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  fic database.** 
1e8c0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
1e8d0 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65   using the conne
1e8e0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73  ction handle pas
1e8f0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
1e900 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72   function .** ar
1e910 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
1e920 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
1e930 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
1e940 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
1e950 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1e960 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75  s to .** this fu
1e970 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f  nction. The seco
1e980 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1e990 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
1e9a0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1e9b0 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
1e9c0 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74   "temp" or an at
1e9d0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
1e9e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
1e9f0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
1ea00 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69  le or NULL. If i
1ea10 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
1ea20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
1ea30 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63  abases are searc
1ea40 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74  hed.** for the t
1ea50 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73  able using the s
1ea60 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73  ame algorithm as
1ea70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
1ea80 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a  gine uses to .**
1ea90 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
1eaa0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
1eab0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ences..**.** The
1eac0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
1ead0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1eae0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72  this function ar
1eaf0 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20  e the table and 
1eb00 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20  column .** name 
1eb10 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
1eb20 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
1eb30 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
1eb40 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
1eb50 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c   .** may be NULL
1eb60 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66  ..**.** Meta inf
1eb70 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75  ormation is retu
1eb80 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20  rned by writing 
1eb90 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f  to the memory lo
1eba0 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61  cations passed a
1ebb0 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64  s.** the 5th and
1ebc0 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61   subsequent para
1ebd0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
1ebe0 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20  unction. Any of 
1ebf0 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65  these .** argume
1ec00 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c  nts may be NULL,
1ec10 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1ec20 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1ec30 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61   element of meta
1ec40 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   .** information
1ec50 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a   is ommitted..**
1ec60 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72  .** <pre>.** Par
1ec70 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70 75  ameter     Outpu
1ec80 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73 63  t Type      Desc
1ec90 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d  ription.** -----
1eca0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ecb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1ecc0 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20  *.**   5th      
1ecd0 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
1ece0 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a      Data type.**
1ecf0 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20 63     6th         c
1ed00 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
1ed10 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61  Name of the defa
1ed20 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
1ed30 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68  quence .**   7th
1ed40 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
1ed50 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
1ed60 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73  f the column has
1ed70 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
1ed80 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20  traint.**   8th 
1ed90 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20          int     
1eda0 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66           True if
1edb0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70   the column is p
1edc0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
1edd0 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20  RY KEY.**   9th 
1ede0 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20          int     
1edf0 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66           True if
1ee00 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41   the column is A
1ee10 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20  UTOINCREMENT.** 
1ee20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20  </pre>.**.**.** 
1ee30 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
1ee40 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
1ee50 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
1ee60 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
1ee70 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e   .** declaration
1ee80 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74   type and collat
1ee90 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
1eea0 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c  valid only until
1eeb0 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61   the next .** ca
1eec0 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65  ll to any sqlite
1eed0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
1eee0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
1eef0 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
1ef00 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
1ef10 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73  then an error is
1ef20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1ef30 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
1ef40 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
1ef50 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
1ef60 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a  rowid_" and an .
1ef70 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  ** INTEGER PRIMA
1ef80 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61  RY KEY column ha
1ef90 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
1efa0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
1efb0 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20   the output .** 
1efc0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
1efd0 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
1efe0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
1eff0 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20  olumn. If there 
1f000 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69  is no.** explici
1f010 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b  tly declared IPK
1f020 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
1f030 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74  e output paramet
1f040 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 0a  ers are set as .
1f050 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  ** follows:.**.*
1f060 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
1f070 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
1f080 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
1f090 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
1f0a0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
1f0b0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
1f0c0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
1f0d0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
1f0e0 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
1f0f0 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  re>.**.** This f
1f100 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
1f110 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
1f120 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
1f130 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
1f140 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
1f150 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
1f160 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
1f170 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
1f180 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
1f190 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
1f1a0 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64  SQLITE error cod
1f1b0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  e is returned an
1f1c0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
1f1d0 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68  ge.** left in th
1f1e0 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
1f1f0 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  e (to be retriev
1f200 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
1f210 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
1f220 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
1f230 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
1f240 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
1f250 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1f260 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42  e.** SQLITE_ENAB
1f270 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
1f280 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20  TA preprocessor 
1f290 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1f2a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1f2b0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
1f2c0 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
1f2d0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1f2e0 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
1f2f0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
1f300 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
1f310 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
1f320 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
1f330 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
1f340 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
1f350 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
1f360 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1f370 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
1f380 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
1f390 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
1f3a0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
1f3b0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
1f3c0 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
1f3d0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
1f3e0 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
1f3f0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
1f400 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
1f410 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
1f420 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
1f430 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
1f440 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
1f450 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
1f460 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
1f470 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
1f480 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
1f490 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
1f4a0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
1f4b0 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
1f4c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
1f4d0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
1f4e0 6c 75 6d 73 20 69 73 20 61 75 74 6f 2d 69 6e 63  lums is auto-inc
1f4f0 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
1f500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
1f510 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
1f520 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f  **.** Attempt to
1f530 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20   load an SQLite 
1f540 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
1f550 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
1f560 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65  he file.** zFile
1f570 2e 20 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69  .  The entry poi
1f580 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a 50  nt is zProc.  zP
1f590 72 6f 63 20 6d 61 79 20 62 65 20 30 20 69 6e 20  roc may be 0 in 
1f5a0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 0a 2a  which case the.*
1f5b0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  * name of the en
1f5c0 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c  try point defaul
1f5d0 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
1f5e0 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
1f5f0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53 51  **.** Return [SQ
1f600 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
1f610 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ess and [SQLITE_
1f620 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68  ERROR] if someth
1f630 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
1f640 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f  **.** If an erro
1f650 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45  r occurs and pzE
1f660 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20  rrMsg is not 0, 
1f670 74 68 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72 72  then fill *pzErr
1f680 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72  Msg with .** err
1f690 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 2e  or message text.
1f6a0 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
1f6b0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72  nction should fr
1f6c0 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a  ee this memory.*
1f6d0 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  * by calling [sq
1f6e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1f6f0 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c  *.** Extension l
1f700 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
1f710 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1f720 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
1f730 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
1f740 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
1f750 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20 61  ng this API or a
1f760 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  n error will be 
1f770 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  returned..*/.int
1f780 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
1f790 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74  tension(.  sqlit
1f7a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f7b0 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74   /* Load the ext
1f7c0 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73  ension into this
1f7d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f7e0 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  tion */.  const 
1f7f0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20  char *zFile,    
1f800 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73  /* Name of the s
1f810 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f  hared library co
1f820 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69  ntaining extensi
1f830 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
1f840 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a  ar *zProc,    /*
1f850 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44   Entry point.  D
1f860 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c  erived from zFil
1f870 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72  e if 0 */.  char
1f880 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20   **pzErrMsg     
1f890 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d    /* Put error m
1f8a0 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e  essage here if n
1f8b0 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ot 0 */.);../*.*
1f8c0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
1f8d0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
1f8e0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
1f8f0 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74  .**.** So as not
1f900 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74   to open securit
1f910 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72  y holes in older
1f920 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
1f930 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70  at are.** unprep
1f940 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74  ared to deal wit
1f950 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  h extension load
1f960 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65  ing, and as a me
1f970 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67  ans of disabling
1f980 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** extension lo
1f990 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c  ading while eval
1f9a0 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65  uating user-ente
1f9b0 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c  red SQL, the fol
1f9c0 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73  lowing.** API is
1f9d0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72   provided to tur
1f9e0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  n the [sqlite3_l
1f9f0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1fa00 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e   mechanism on an
1fa10 64 0a 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69 73  d.** off.  It is
1fa20 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
1fa30 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38    See ticket #18
1fa40 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74  63..**.** Call t
1fa50 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1fa60 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72   onoff==1 to tur
1fa70 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  n extension load
1fa80 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61  ing on.** and ca
1fa90 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
1faa0 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62  ==0 to turn it b
1fab0 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a  ack off again..*
1fac0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
1fad0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
1fae0 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
1faf0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
1fb00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
1fb10 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20  ke Arrangements 
1fb20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  To Automatically
1fb30 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
1fb40 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  on.**.** Registe
1fb50 72 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65  r an extension e
1fb60 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20  ntry point that 
1fb70 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
1fb80 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1fb90 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62  ever a new datab
1fba0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1fbb0 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a  s opened using.*
1fbc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
1fbd0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1fbe0 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
1fbf0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
1fc00 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63  **.** This API c
1fc10 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74  an be invoked at
1fc20 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70   program startup
1fc30 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67   in order to reg
1fc40 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ister.** one or 
1fc50 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20  more statically 
1fc60 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e  linked extension
1fc70 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61  s that will be a
1fc80 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61  vailable.** to a
1fc90 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  ll new database 
1fca0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  connections..**.
1fcb0 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 74  ** Duplicate ext
1fcc0 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65  ensions are dete
1fcd0 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20  cted so calling 
1fce0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c  this routine mul
1fcf0 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
1fd00 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
1fd10 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
1fd20 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ss..**.** This r
1fd30 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
1fd40 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
1fd50 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61  xtension in an a
1fd60 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20  rray.** that is 
1fd70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61  obtained from ma
1fd80 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20  lloc().  If you 
1fd90 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  run a memory lea
1fda0 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20  k.** checker on 
1fdb0 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64  your program and
1fdc0 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65   it reports a le
1fdd0 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68  ak because of th
1fde0 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65  is.** array, the
1fdf0 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  n invoke [sqlite
1fe00 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65  3_automatic_exte
1fe10 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 70  nsion_reset()] p
1fe20 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64  rior.** to shutd
1fe30 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
1fe40 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75  memory..**.** Au
1fe50 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
1fe60 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20  ns apply across 
1fe70 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a  all threads..**.
1fe80 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1fe90 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
1fea0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
1feb0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
1fec0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
1fed0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1fee0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
1fef0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
1ff00 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72  sion(void *xEntr
1ff10 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  yPoint);.../*.**
1ff20 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
1ff30 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e   Automatic Exten
1ff40 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
1ff50 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 70  ** Disable all p
1ff60 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
1ff70 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65  ered automatic e
1ff80 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73  xtensions.  This
1ff90 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
1ffa0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
1ffb0 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69   all prior [sqli
1ffc0 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78  te3_automatic_ex
1ffd0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61  tension()].** ca
1ffe0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lls..**.** This 
1fff0 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75  call disabled au
20000 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
20010 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
20020 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
20030 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
20040 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
20050 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
20060 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
20070 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
20080 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
20090 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
200a0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
200b0 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  n(void);.../*.**
200c0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
200d0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
200e0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
200f0 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
20100 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
20110 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
20120 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
20130 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
20140 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
20150 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
20160 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
20170 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
20180 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
20190 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
201a0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
201b0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
201c0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
201d0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
201e0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
201f0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
20200 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73  hanism stablizes
20210 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
20220 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
20230 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
20240 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
20250 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
20260 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
20270 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
20280 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
20290 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
202a0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
202b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
202c0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
202d0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
202e0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
202f0 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
20300 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
20310 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
20320 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
20330 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
20340 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20350 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
20360 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
20370 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73  *.** A module is
20380 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74   a class of virt
20390 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63  ual tables.  Eac
203a0 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69  h module is defi
203b0 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73  ned.** by an ins
203c0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c  tance of the fol
203d0 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
203e0 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72  .  This structur
203f0 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f  e consists.** mo
20400 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
20410 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
20420 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
20430 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
20440 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
20450 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
20460 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
20470 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
20480 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
20490 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
204a0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
204b0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
204c0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
204d0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
204e0 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
204f0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
20500 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
20510 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
20520 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
20530 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
20540 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
20550 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
20560 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
20570 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
20580 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
20590 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
205a0 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
205b0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
205c0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
205d0 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
205e0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
205f0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
20600 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
20610 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
20620 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
20630 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
20640 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
20650 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
20660 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
20670 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
20680 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
20690 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
206a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
206b0 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
206c0 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
206d0 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
206e0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
206f0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
20700 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
20710 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
20720 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
20730 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
20740 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
20750 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
20760 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
20770 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
20780 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
20790 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
207a0 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
207b0 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
207c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
207d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
207e0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
207f0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20800 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
20810 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
20820 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
20830 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
20840 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
20850 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
20860 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
20870 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
20880 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
20890 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
208a0 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
208b0 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
208c0 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
208d0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
208e0 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
208f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
20900 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
20910 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
20920 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
20930 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74  **ppArg);..  int
20940 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
20950 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
20960 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
20970 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  w);.};../*.** Th
20980 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
20990 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
209a0 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74  nd its substruct
209b0 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a  ures is used to.
209c0 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74  ** pass informat
209d0 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63  ion into and rec
209e0 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66  eive the reply f
209f0 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64  rom the xBestInd
20a00 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ex.** method of 
20a10 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  an sqlite3_modul
20a20 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  e.  The fields u
20a30 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
20a40 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
20a50 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
20a60 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
20a70 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
20a80 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
20a90 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
20aa0 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
20ab0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f  s..**.** The aCo
20ac0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
20ad0 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
20ae0 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
20af0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
20b00 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20  :.**.**         
20b10 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a  column OP expr.*
20b20 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73  *.** Where OP is
20b30 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72   =, <, <=, >, or
20b40 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63   >=.  The partic
20b50 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
20b60 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43   stored.** in aC
20b70 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20  onstraint[].op. 
20b80 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   The index of th
20b90 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72  e column is stor
20ba0 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74  ed in .** aConst
20bb0 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
20bc0 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e    aConstraint[].
20bd0 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
20be0 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
20bf0 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
20c00 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
20c10 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
20c20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
20c30 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
20c40 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
20c50 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  not..**.** The o
20c60 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74  ptimizer automat
20c70 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74  ically inverts t
20c80 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  erms of the form
20c90 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e   "expr OP column
20ca0 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f  ".** and makes o
20cb0 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74  ther simplificat
20cc0 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45 52  inos to the WHER
20cd0 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61  E clause in an a
20ce0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74  ttempt to.** get
20cf0 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63   as many WHERE c
20d00 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f  lause terms into
20d10 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20   the form shown 
20d20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c  above as possibl
20d30 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  e..** The aConst
20d40 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
20d50 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
20d60 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
20d70 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20   the correct.** 
20d80 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20  form that refer 
20d90 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
20da0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
20db0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
20dc0 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  *.** Information
20dd0 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
20de0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
20df0 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
20e00 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d  []..** Each term
20e10 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
20e20 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
20e30 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
20e40 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
20e50 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
20e60 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e  d must fill aCon
20e70 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77  straintUsage[] w
20e80 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ith information.
20e90 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61  ** about what pa
20ea0 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73  rameters to pass
20eb0 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66   to xFilter.  If
20ec0 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65   argvIndex>0 the
20ed0 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68  n.** the right-h
20ee0 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
20ef0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43  corresponding aC
20f00 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65  onstraint[] is e
20f10 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20  valuated.** and 
20f20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76  becomes the argv
20f30 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69  Index-th entry i
20f40 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e  n argv.  If aCon
20f50 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
20f60 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
20f70 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
20f80 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
20f90 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
20fa0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed by the.** vir
20fb0 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
20fc0 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67  s not checked ag
20fd0 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ain by SQLite..*
20fe0 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20  *.** The idxNum 
20ff0 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65  and idxPtr value
21000 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61  s are recorded a
21010 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78  nd passed into x
21020 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74  Filter..** sqlit
21030 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65  e3_free() is use
21040 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
21050 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64   if needToFreeId
21060 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a  xPtr is true..**
21070 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43  .** The orderByC
21080 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
21090 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78  at output from x
210a0 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75  Filter will occu
210b0 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72  r in.** the corr
210c0 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74  ect order to sat
210d0 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42  isfy the ORDER B
210e0 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74  Y clause so that
210f0 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20   no separate.** 
21100 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20  sorting step is 
21110 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
21120 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  The estimatedCos
21130 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73  t value is an es
21140 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f  timate of the co
21150 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a  st of doing the.
21160 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f  ** particular lo
21170 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63  okup.  A full sc
21180 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69  an of a table wi
21190 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  th N entries sho
211a0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f  uld have.** a co
211b0 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61  st of N.  A bina
211c0 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74  ry search of a t
211d0 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65  able of N entrie
211e0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a  s should have a.
211f0 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f  ** cost of appro
21200 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e  ximately log(N).
21210 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
21220 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a  e3_index_info {.
21230 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20    /* Inputs */. 
21240 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73   const int nCons
21250 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e  traint;     /* N
21260 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
21270 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20   in aConstraint 
21280 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63  */.  const struc
21290 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
212a0 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
212b0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
212c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
212d0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
212e0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
212f0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
21300 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
21310 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
21320 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
21330 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
21340 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
21350 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
21360 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
21370 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
21380 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
21390 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
213a0 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
213b0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
213c0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63 6f  gnore */.  } *co
213d0 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 3b  nst aConstraint;
213e0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
213f0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
21400 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
21410 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65 72  const int nOrder
21420 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  By;        /* Nu
21430 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
21440 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
21450 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ause */.  const 
21460 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
21470 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20  ndex_orderby {. 
21480 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
21490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
214a0 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a   Column number *
214b0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
214c0 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20  char desc;      
214d0 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53   /* True for DES
214e0 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53  C.  False for AS
214f0 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74  C. */.  } *const
21500 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   aOrderBy;      
21510 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20     /* The ORDER 
21520 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20  BY clause */..  
21530 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20  /* Outputs */.  
21540 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
21550 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f  ndex_constraint_
21560 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20  usage {.    int 
21570 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
21580 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63       /* if >0, c
21590 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72  onstraint is par
215a0 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69  t of argv to xFi
215b0 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69  lter */.    unsi
215c0 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
215d0 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
215e0 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
215f0 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
21600 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f  /.  } *const aCo
21610 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20  nstraintUsage;. 
21620 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20   int idxNum;    
21630 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
21640 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64  umber used to id
21650 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78  entify the index
21660 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53   */.  char *idxS
21670 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  tr;             
21680 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73   /* String, poss
21690 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  ibly obtained fr
216a0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
216b0 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54  c */.  int needT
216c0 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20  oFreeIdxStr;    
216d0 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72    /* Free idxStr
216e0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
216f0 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f  ree() if true */
21700 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f  .  int orderByCo
21710 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a  nsumed;       /*
21720 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20   True if output 
21730 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72  is already order
21740 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65  ed */.  double e
21750 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20  stimatedCost;   
21760 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20     /* Estimated 
21770 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68  cost of using th
21780 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23  is index */.};.#
21790 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
217a0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
217b0 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  Q    2.#define S
217c0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
217d0 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23  TRAINT_GT    4.#
217e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
217f0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
21800 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53  E    8.#define S
21810 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
21820 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a  TRAINT_LT    16.
21830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
21840 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
21850 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  GE    32.#define
21860 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
21870 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36  NSTRAINT_MATCH 6
21880 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  4../*.** This ro
21890 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f  utine is used to
218a0 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
218b0 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68  module name with
218c0 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f   an SQLite.** co
218d0 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c  nnection.  Modul
218e0 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
218f0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
21900 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a  e creating new.*
21910 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
21920 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20   on the module, 
21930 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  or before using 
21940 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74  preexisting virt
21950 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66  ual.** tables of
21960 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a   the module..*/.
21970 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
21980 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
21990 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
219a0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
219b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
219c0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
219d0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
219e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
219f0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
21a00 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
21a10 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
21a20 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
21a30 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
21a40 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
21a50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21a60 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
21a70 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
21a80 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a  xConnect */.);..
21a90 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  /*.** This routi
21aa0 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  ne is identical 
21ab0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  to the sqlite3_c
21ac0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d  reate_module() m
21ad0 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20  ethod above,.** 
21ae0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
21af0 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74  llows a destruct
21b00 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  or function to b
21b10 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20  e specified. It 
21b20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20  is.** even more 
21b30 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61  experimental tha
21b40 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68  n the rest of th
21b50 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
21b60 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   API..*/.int sql
21b70 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
21b80 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
21b90 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
21ba0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
21bb0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
21bc0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
21bd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
21be0 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
21bf0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
21c00 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
21c10 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
21c20 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *,    /* Method
21c30 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
21c40 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
21c50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21c60 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
21c70 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
21c80 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
21c90 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
21ca0 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
21cb0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
21cc0 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
21cd0 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
21ce0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
21cf0 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
21d00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
21d10 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
21d20 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
21d30 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ar instance of t
21d40 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
21d50 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
21d60 2a 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74 6f  * be taylored to
21d70 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
21d80 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
21d90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
21da0 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f  .   The.** purpo
21db0 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
21dc0 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
21dd0 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
21de0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f  s that are commo
21df0 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  n.** to all modu
21e00 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
21e10 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
21e20 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
21e30 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
21e40 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
21e50 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
21e60 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
21e70 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
21e80 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  () to zErrMsg.  
21e90 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
21ea0 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
21eb0 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
21ec0 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
21ed0 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
21ee0 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69  e3_free().** pri
21ef0 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
21f00 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
21f10 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20  zErrMsg.  After 
21f20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
21f30 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
21f40 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
21f50 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
21f60 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
21f70 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
21f80 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
21f90 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
21fa0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
21fb0 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
21fc0 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20  .  Note.** that 
21fd0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
21fe0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72  ) and sqlite3_fr
21ff0 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e  ee() are used on
22000 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
22010 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74  ld.** since virt
22020 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63  ual tables are c
22030 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e  ommonly implemen
22040 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20  ted in loadable 
22050 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68  extensions which
22060 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  .** do not have 
22070 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65  access to sqlite
22080 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71  3MPrintf() or sq
22090 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a  lite3Free()..*/.
220a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
220b0 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
220c0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
220d0 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
220e0 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
220f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
22100 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
22110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22120 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
22130 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ally */.  char *
22140 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
22150 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
22160 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
22170 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
22180 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
22190 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
221a0 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
221b0 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
221c0 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
221d0 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64  };../* Every mod
221e0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
221f0 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
22200 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
22210 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
22220 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72   to describe cur
22230 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20  sors that point 
22240 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  into the virtual
22250 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75   table and are u
22260 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74  sed.** to loop t
22270 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75  hrough the virtu
22280 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f  al table.  Curso
22290 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  rs are created u
222a0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65  sing the.** xOpe
222b0 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  n method of the 
222c0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f  module.  Each mo
222d0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
222e0 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a  ion will define.
222f0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
22300 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63  f a cursor struc
22310 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73  ture to suit its
22320 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a   own needs..**.*
22330 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73  * This superclas
22340 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65  s exists in orde
22350 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c  r to define fiel
22360 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72  ds of the cursor
22370 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d   that.** are com
22380 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65  mon to all imple
22390 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73  mentations..*/.s
223a0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
223b0 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71  ab_cursor {.  sq
223c0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
223d0 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75  b;      /* Virtu
223e0 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73  al table of this
223f0 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20   cursor */.  /* 
22400 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
22410 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
22420 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
22430 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
22440 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
22450 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20  The xCreate and 
22460 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73  xConnect methods
22470 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65   of a module use
22480 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
22490 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65  PI.** to declare
224a0 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65   the format (the
224b0 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74   names and datat
224c0 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ypes of the colu
224d0 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76  mns) of.** the v
224e0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68  irtual tables th
224f0 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f  ey implement..*/
22500 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63  .int sqlite3_dec
22510 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
22520 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
22530 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a  zCreateTable);..
22540 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  /*.** Virtual ta
22550 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
22560 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
22570 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
22580 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
22590 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63  ng the xFindFunc
225a0 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75  tion method.  Bu
225b0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
225c0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
225d0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
225e0 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
225f0 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  e overloaded..**
22600 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b  .** This API mak
22610 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
22620 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
22630 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
22640 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
22650 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
22660 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
22670 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
22680 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
22690 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
226a0 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
226b0 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
226c0 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  eated.  The impl
226d0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
226e0 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
226f0 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20  n always causes 
22700 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  an exception to 
22710 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a  be thrown.  So.*
22720 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  * the new functi
22730 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66  on is not good f
22740 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69  or anything by i
22750 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79  tself.  Its only
22760 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74  .** purpose is t
22770 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c  o be a place-hol
22780 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
22790 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
227a0 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61  ded.** by virtua
227b0 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  l tables..**.** 
227c0 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20  This API should 
227d0 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61  be considered pa
227e0 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  rt of the virtua
227f0 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
22800 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65  e,.** which is e
22810 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
22820 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
22830 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
22840 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74  3_overload_funct
22850 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  ion(sqlite3*, co
22860 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e  nst char *zFuncN
22870 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a  ame, int nArg);.
22880 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
22890 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
228a0 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
228b0 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ism defined abov
228c0 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f  e (back up.** to
228d0 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72   a comment remar
228e0 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f  kably similar to
228f0 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75   this one) is cu
22900 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
22910 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
22920 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
22930 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
22940 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
22950 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
22960 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
22970 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
22980 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
22990 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
229a0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
229b0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
229c0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c   mechanism stabl
229d0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
229e0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
229f0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
22a00 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
22a10 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
22a20 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
22a30 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  **.****** EXPERI
22a40 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
22a50 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
22a60 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
22a70 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a  ********.*/../*.
22a80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
22a90 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
22aa0 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69   BLOB.**.** An i
22ab0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66  nstance of the f
22ac0 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20  ollowing opaque 
22ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73 65  structure is use
22ae0 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65  d to .** represe
22af0 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c  nt an blob-handl
22b00 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c  e.  A blob-handl
22b10 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 0a  e is created by.
22b20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
22b30 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73  _open()] and des
22b40 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
22b50 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
22b60 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
22b70 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
22b80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
22b90 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
22ba0 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
22bb0 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
22bc0 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
22bd0 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c  ctions of the bl
22be0 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  ob..** The [sqli
22bf0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
22c00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
22c10 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
22c20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62  the.** blob in b
22c30 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
22c40 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
22c50 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
22c60 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
22c70 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
22c80 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
22c90 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61  I/O.**.** Open a
22ca0 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62   handle to the b
22cb0 6c 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72  lob located in r
22cc0 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e  ow iRow,, column
22cd0 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61   zColumn, .** ta
22ce0 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
22cf0 74 61 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e  tabase zDb. i.e.
22d00 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74   the same blob t
22d10 68 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20  hat would.** be 
22d20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
22d30 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
22d40 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
22d50 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
22d60 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f  HERE rowid = iRo
22d70 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  w;.** </pre>.**.
22d80 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20  ** If the flags 
22d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
22da0 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20  -zero, the blob 
22db0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a  is opened for .*
22dc0 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65  * read and write
22dd0 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69   access. If it i
22de0 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62  s zero, the blob
22df0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22e00 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a  ead .** access..
22e10 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
22e20 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
22e30 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
22e40 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74  e new .** [sqlit
22e50 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68  e3_blob | blob h
22e60 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
22e70 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a  n to *ppBlob..**
22e80 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
22e90 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
22ea0 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79  rned and .** any
22eb0 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74   value written t
22ec0 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64  o *ppBlob should
22ed0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
22ee0 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54  the caller..** T
22ef0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
22f00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68  s the database-h
22f10 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65  andle error code
22f20 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
22f30 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
22f40 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
22f50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22f60 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
22f70 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f  t sqlite3_blob_o
22f80 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  pen(.  sqlite3*,
22f90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
22fa0 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  Db,.  const char
22fb0 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73   *zTable,.  cons
22fc0 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c  t char *zColumn,
22fd0 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  .  sqlite3_int64
22fe0 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61   iRow,.  int fla
22ff0 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c  gs,.  sqlite3_bl
23000 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a  ob **ppBlob.);..
23010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23020 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
23030 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  ndle.**.** Close
23040 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65   an open [sqlite
23050 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61  3_blob | blob ha
23060 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndle]..*/.int sq
23070 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
23080 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
23090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
230a0 46 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20 53  F:  Return The S
230b0 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
230c0 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  LOB.**.** Return
230d0 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
230e0 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61  es of the blob a
230f0 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
23100 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  e open .** [sqli
23110 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
23120 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
23130 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  s an argument..*
23140 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
23150 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ob_bytes(sqlite3
23160 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
23170 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64   CAPI3REF:  Read
23180 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
23190 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
231a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
231b0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
231c0 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  ead data from an
231d0 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
231e0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
231f0 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61  andle] into a ca
23200 6c 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  ller supplied bu
23210 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
23220 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
23230 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a  ied into buffer.
23240 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70  ** z from the op
23250 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
23260 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
23270 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  set..**.** On su
23280 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
23290 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
232a0 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
232b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
232c0 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
232d0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  e] or an.** [SQL
232e0 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
232f0 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
23300 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
23310 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
23320 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69  3_blob_read(sqli
23330 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64  te3_blob *, void
23340 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
23350 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
23360 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74   CAPI3REF:  Writ
23370 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c  e Data Into A BL
23380 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
23390 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
233a0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
233b0 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20  write data into 
233c0 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c  an open .** [sql
233d0 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
233e0 2d 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20  -handle] from a 
233f0 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  user supplied bu
23400 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
23410 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
23420 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66  ied from the buf
23430 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  fer.** pointed t
23440 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20  o by z into the 
23450 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74  open blob, start
23460 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
23470 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ffset..**.** If 
23480 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
23490 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
234a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
234b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
234c0 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
234d0 66 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65  for writing (the
234e0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
234f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
23500 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61  b_open()].*** wa
23510 73 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75  s zero), this fu
23520 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
23530 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
23540 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
23550 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d  ction may only m
23560 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e  odify the conten
23570 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20  ts of the blob, 
23580 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
23590 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73  sible to increas
235a0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
235b0 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20  blob using this 
235c0 41 50 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65  API. If.** offse
235d0 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
235e0 73 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66  s than n bytes f
235f0 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
23600 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51  he blob, .** [SQ
23610 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
23620 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
23630 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
23640 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
23650 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
23660 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
23670 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  se, an .** [SQLI
23680 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74  TE_ERROR | SQLit
23690 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72  e error code] or
236a0 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   an.** [SQLITE_I
236b0 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
236c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
236d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   is returned..*/
236e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
236f0 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
23700 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
23710 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
23720 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
23730 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69  ** CAPI3REF:  Vi
23740 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
23750 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20  m Objects.**.** 
23760 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
23770 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
23780 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
23790 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
237a0 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
237b0 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
237c0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
237d0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
237e0 4d 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65  Most builds come
237f0 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
23800 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
23810 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
23820 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
23830 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
23840 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
23850 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
23860 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
23870 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
23880 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
23890 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
238a0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
238b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
238c0 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
238d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
238e0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
238f0 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20  n its.** name.  
23900 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
23910 65 6e 73 69 74 69 76 65 2e 20 20 49 66 20 74 68  ensitive.  If th
23920 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
23930 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
23940 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
23950 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20   If zVfsName is 
23960 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
23970 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73  fault .** VFS is
23980 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
23990 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72   New VFSes are r
239a0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
239b0 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
239c0 74 65 72 28 29 2e 20 20 45 61 63 68 0a 2a 2a 20  ter().  Each.** 
239d0 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20  new VFS becomes 
239e0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
239f0 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  if the makeDflt 
23a00 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20  flag is set..** 
23a10 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e  The same VFS can
23a20 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
23a30 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
23a40 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a  thout injury..**
23a50 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73   To make an exis
23a60 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
23a70 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
23a80 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
23a90 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
23aa0 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20  eDflt flag set. 
23ab0 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e   If two differen
23ac0 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65  t VFSes with the
23ad0 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  .** same name ar
23ae0 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68  e registered, th
23af0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
23b00 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a  defined.  If a.*
23b10 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65  * VFS is registe
23b20 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20  red with a name 
23b30 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20  that is NULL or 
23b40 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
23b50 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
23b60 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
23b70 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67  ed..** .** Unreg
23b80 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
23b90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
23ba0 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
23bb0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74  terface..** If t
23bc0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
23bd0 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20  s unregistered, 
23be0 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63  another VFS is c
23bf0 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20  hosen as.** the 
23c00 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68  default.  The ch
23c10 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77  oice for the new
23c20 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72   VFS is arbitrar
23c30 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66  y..*/.sqlite3_vf
23c40 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  s *sqlite3_vfs_f
23c50 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ind(const char *
23c60 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73  zVfsName);.int s
23c70 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
23c80 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
23c90 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b  , int makeDflt);
23ca0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
23cb0 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69  _unregister(sqli
23cc0 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a  te3_vfs*);../*.*
23cd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
23ce0 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  xes.**.** The SQ
23cf0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
23d00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
23d10 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63  r thread.** sync
23d20 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68  hronization.  Th
23d30 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
23d40 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
23d50 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
23d60 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
23d70 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
23d80 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
23d90 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
23da0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
23db0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
23dc0 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
23dd0 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
23de0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23df0 73 20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d  s .** of these m
23e00 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20  utex routines.  
23e10 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69  An appropriate i
23e20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
23e30 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74   is selected aut
23e40 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f  omatically at co
23e50 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65  mpile-time.  The
23e60 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d   following.** im
23e70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72  plementations ar
23e80 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  e available in t
23e90 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a  he SQLite core:.
23ea0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
23eb0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
23ec0 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_OS2.** <li>   
23ed0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
23ee0 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  READ.** <li>   S
23ef0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a  QLITE_MUTEX_W32.
23f00 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
23f10 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c  _MUTEX_NOOP.** <
23f20 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
23f30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
23f40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23f50 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74  is a set of rout
23f60 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f  ines .** that do
23f70 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69  es no real locki
23f80 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70  ng and is approp
23f90 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e  riate for use in
23fa0 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68   .** a single-th
23fb0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
23fc0 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  on.  The SQLITE_
23fd0 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51  MUTEX_OS2,.** SQ
23fe0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
23ff0 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AD, and SQLITE_M
24000 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65  UTEX_W32 impleme
24010 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
24020 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
24030 75 73 65 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69  use on os/2, uni
24040 78 2c 20 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a  x, and windows..
24050 2a 2a 20 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  ** .** If SQLite
24060 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
24070 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  h the SQLITE_MUT
24080 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f  EX_APPDEF prepro
24090 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20  cessor.** macro 
240a0 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d  defined (with "-
240b0 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50  DSQLITE_MUTEX_AP
240c0 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e  PDEF=1"), then n
240d0 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  o mutex.** imple
240e0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63  mentation is inc
240f0 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c  luded with the l
24100 69 62 72 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20  ibrary.  The.** 
24110 6d 75 74 65 78 20 69 6e 74 65 72 66 61 63 65 20  mutex interface 
24120 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
24130 20 68 65 72 65 20 62 65 63 6f 6d 65 20 65 78 74   here become ext
24140 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e  ernal.** referen
24150 63 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ces in the SQLit
24160 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68  e library for wh
24170 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ich implementati
24180 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70  ons.** must be p
24190 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 61  rovided by the a
241a0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  pplication.  Thi
241b0 73 20 66 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77  s facility allow
241c0 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  s an.** applicat
241d0 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ion that links a
241e0 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 74 6f  gainst SQLite to
241f0 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e   provide its own
24200 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
24210 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f 75 74  entation without
24220 20 68 61 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66   having to modif
24230 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
24240 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
24250 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
24260 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63  () routine alloc
24270 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75  ates a new.** mu
24280 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20  tex and returns 
24290 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
242a0 20 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20    If it returns 
242b0 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
242c0 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
242d0 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
242e0 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 0a  ocated.  SQLite.
242f0 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69  ** will unwind i
24300 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74  ts stack and ret
24310 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 54  urn an error.  T
24320 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
24330 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
24340 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f  alloc() is one o
24350 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
24360 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a  constants:.**.**
24370 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
24380 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
24390 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
243a0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
243b0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
243c0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
243d0 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  STER.** <li>  SQ
243e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
243f0 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_MEM.** <li>  S
24400 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
24410 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20  IC_MEM2.** <li> 
24420 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
24430 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69  ATIC_PRNG.** <li
24440 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
24450 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f  STATIC_LRU.** </
24460 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
24470 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  rst two constant
24480 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  s cause sqlite3_
24490 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f  mutex_alloc() to
244a0 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77   create.** a new
244b0 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77   mutex.  The new
244c0 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
244d0 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
244e0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
244f0 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
24500 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
24510 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
24520 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
24530 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
24540 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
24550 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
24560 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
24570 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
24580 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
24590 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
245a0 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
245b0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
245c0 20 74 6f 2e 20 20 42 75 74 20 53 51 4c 69 74 65   to.  But SQLite
245d0 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65   will only reque
245e0 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d  st a recursive m
245f0 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73  utex in.** cases
24600 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79   where it really
24610 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 49 66 20   needs one.  If 
24620 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63  a faster non-rec
24630 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20  ursive mutex.** 
24640 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
24650 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74  s available on t
24660 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d  he host platform
24670 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73  , the mutex subs
24680 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72  ystem.** might r
24690 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74  eturn such a mut
246a0 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ex in response t
246b0 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  o SQLITE_MUTEX_F
246c0 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  AST..**.** The o
246d0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
246e0 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
246f0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
24700 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
24710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
24720 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
24730 67 20 6d 75 74 65 78 2e 20 20 46 6f 75 72 20 73  g mutex.  Four s
24740 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
24750 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
24760 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
24770 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
24780 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
24790 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
247a0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
247b0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
247c0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
247d0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
247e0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
247f0 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
24800 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
24810 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
24820 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
24830 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
24840 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
24850 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
24860 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
24870 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
24880 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 69 66  .** Note that if
24890 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61   one of the dyna
248a0 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65  mic mutex parame
248b0 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ters (SQLITE_MUT
248c0 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51  EX_FAST.** or SQ
248d0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
248e0 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68  SIVE) is used th
248f0 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  en sqlite3_mutex
24900 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75  _alloc().** retu
24910 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20  rns a different 
24920 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63  mutex on every c
24930 61 6c 6c 2e 20 20 42 75 74 20 66 6f 72 20 74 68  all.  But for th
24940 65 20 73 74 61 74 69 63 20 0a 2a 2a 20 6d 75 74  e static .** mut
24950 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61  ex types, the sa
24960 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75  me mutex is retu
24970 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61  rned on every ca
24980 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74  ll that has.** t
24990 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d  he same type num
249a0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ber..**.** The s
249b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
249c0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c  e() routine deal
249d0 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 6f  locates a previo
249e0 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  usly.** allocate
249f0 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e  d dynamic mutex.
24a00 20 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65    SQLite is care
24a10 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74  ful to deallocat
24a20 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d  e every.** dynam
24a30 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74  ic mutex that it
24a40 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65   allocates.  The
24a50 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
24a60 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 20   must not be in 
24a70 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65  .** use when the
24a80 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65  y are deallocate
24a90 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20 74  d.  Attempting t
24aa0 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73  o deallocate a s
24ab0 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72  tatic.** mutex r
24ac0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
24ad0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20 53  ned behavior.  S
24ae0 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c  QLite never deal
24af0 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61  locates.** a sta
24b00 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a  tic mutex..**.**
24b10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
24b20 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
24b30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
24b40 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
24b50 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
24b60 61 20 6d 75 74 65 78 2e 20 20 49 66 20 61 6e 6f  a mutex.  If ano
24b70 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61  ther thread is a
24b80 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68  lready within th
24b90 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69  e mutex,.** sqli
24ba0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
24bb0 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64  ) will block and
24bc0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
24bd0 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ry() will return
24be0 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
24bf0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75    The sqlite3_mu
24c00 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
24c10 61 63 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ace returns SQLI
24c20 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73 75  TE_OK.** upon su
24c30 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20  ccessful entry. 
24c40 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64   Mutexes created
24c50 20 75 73 69 6e 67 20 53 51 4c 49 54 45 5f 4d 55   using SQLITE_MU
24c60 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61  TEX_RECURSIVE ca
24c70 6e 0a 2a 2a 20 62 65 20 65 6e 74 65 72 65 64 20  n.** be entered 
24c80 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62  multiple times b
24c90 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
24ca0 64 2e 20 20 49 6e 20 73 75 63 68 20 63 61 73 65  d.  In such case
24cb0 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
24cc0 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
24cd0 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
24ce0 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
24cf0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
24d00 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 49 66 20   can enter.  If 
24d10 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
24d20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
24d30 6e 79 20 6f 74 68 65 72 20 6b 69 6e 64 20 6f 66  ny other kind of
24d40 20 6d 75 74 65 78 0a 2a 2a 20 6d 6f 72 65 20 74   mutex.** more t
24d50 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
24d60 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
24d70 6e 65 64 2e 20 20 20 53 51 4c 69 74 65 20 77 69  ned.   SQLite wi
24d80 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
24d90 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
24da0 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
24db0 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a   of mutexes..**.
24dc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
24dd0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
24de0 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
24df0 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
24e00 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
24e10 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
24e20 72 65 61 64 2e 20 20 54 68 65 20 62 65 68 61 76  read.  The behav
24e30 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
24e40 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
24e50 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
24e60 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
24e70 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  .** calling thre
24e80 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72  ad or is not cur
24e90 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64  rently allocated
24ea0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
24eb0 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  * never do eithe
24ec0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
24ed0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  o: [sqlite3_mute
24ee0 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73  x_held()] and [s
24ef0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
24f00 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69  held()]..*/.sqli
24f10 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74  te3_mutex *sqlit
24f20 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69  e3_mutex_alloc(i
24f30 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
24f40 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c  3_mutex_free(sql
24f50 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
24f60 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
24f70 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d  _enter(sqlite3_m
24f80 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  utex*);.int sqli
24f90 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71  te3_mutex_try(sq
24fa0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
24fb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
24fc0 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f  x_leave(sqlite3_
24fd0 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
24fe0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
24ff0 56 65 72 69 66 63 61 74 69 6f 6e 20 52 6f 75 74  Verifcation Rout
25000 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ines.**.** The s
25010 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
25020 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
25030 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
25040 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
25050 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
25060 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
25070 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
25080 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a  e SQLite core.**
25090 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73   never uses thes
250a0 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70  e routines excep
250b0 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65  t inside an asse
250c0 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61  rt() and applica
250d0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76  tions.** are adv
250e0 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74  ised to follow t
250f0 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63  he lead of the c
25100 6f 72 65 2e 20 20 54 68 65 20 63 6f 72 65 20 6f  ore.  The core o
25110 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20  nly.** provides 
25120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
25130 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
25140 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  es when it is co
25150 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74  mpiled.** with t
25160 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  he SQLITE_DEBUG 
25170 66 6c 61 67 2e 20 20 45 78 74 65 72 6e 61 6c 20  flag.  External 
25180 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
25190 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c  tions.** are onl
251a0 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  y required to pr
251b0 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74  ovide these rout
251c0 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44  ines if SQLITE_D
251d0 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e  EBUG is.** defin
251e0 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47  ed and if NDEBUG
251f0 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e   is not defined.
25200 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
25210 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74  tines should ret
25220 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
25230 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61  mutex in their a
25240 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65  rgument.** is he
25250 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20  ld or not held, 
25260 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79  respectively, by
25270 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
25280 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ead..**.** The i
25290 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
252a0 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
252b0 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f   provided versio
252c0 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72  ns of these.** r
252d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74  outines that act
252e0 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49  ually work..** I
252f0 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  f the implementa
25300 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72  tion does not pr
25310 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a  ovide working.**
25320 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
25330 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20  se routines, it 
25340 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20  should at least 
25350 70 72 6f 76 69 64 65 20 73 74 75 62 73 0a 2a 2a  provide stubs.**
25360 20 74 68 61 74 20 61 6c 77 61 79 73 20 72 65 74   that always ret
25370 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74  urn true so that
25380 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65   one does not ge
25390 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 61 73  t spurious.** as
253a0 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
253b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61  ..**.** If the a
253c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
253d0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
253e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
253f0 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f  r then.** the ro
25400 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74  utine should ret
25410 75 72 6e 20 31 2e 20 20 54 68 69 73 20 73 65 65  urn 1.  This see
25420 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69  ms counter-intui
25430 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c  tive since.** cl
25440 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20  early the mutex 
25450 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69  cannot be held i
25460 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  f it does not ex
25470 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a  ist.  But the.**
25480 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20   the reason the 
25490 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65  mutex does not e
254a0 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20  xist is because 
254b0 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74  the build is not
254c0 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65  .** using mutexe
254d0 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f  s.  And we do no
254e0 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72  t want the asser
254f0 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  t() containing t
25500 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  he.** call to sq
25510 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
25520 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61  () to fail, so a
25530 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
25540 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f   is.** the appro
25550 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20  priate thing to 
25560 64 6f 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  do.  The sqlite3
25570 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
25580 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73   .** interface s
25590 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
255a0 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
255b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
255c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  /.int sqlite3_mu
255d0 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33  tex_held(sqlite3
255e0 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
255f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
25600 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
25610 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
25620 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65  3REF: Mutex Type
25630 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
25640 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
25650 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61  ()] interface ta
25660 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
25670 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69  ument.** which i
25680 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
25690 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
256a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
256b0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20  ITE_MUTEX_FAST  
256c0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
256d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
256e0 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  X_RECURSIVE     
256f0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
25700 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
25710 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65  _MASTER    2.#de
25720 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
25730 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20  X_STATIC_MEM    
25740 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33     3  /* sqlite3
25750 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65  _malloc() */.#de
25760 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
25770 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20  X_STATIC_MEM2   
25780 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
25790 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
257a0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
257b0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
257c0 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
257d0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
257e0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
257f0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
25800 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
25810 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
25820 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
25830 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e  F: Low-Level Con
25840 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65  trol Of Database
25850 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Files.**.** The
25860 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
25870 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
25880 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72 65  ace makes a dire
25890 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a  ct call to the.*
258a0 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  * xFileControl m
258b0 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b 73  ethod for the [s
258c0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
258d0 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  s] object associ
258e0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 70  ated.** with a p
258f0 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
25900 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  se identified by
25910 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
25920 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 6e 61  ment.  The.** na
25930 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
25940 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61  se is the name a
25950 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64  ssigned to the d
25960 61 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a  atabase by the.*
25970 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  * <a href="lang_
25980 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54  attach.html">ATT
25990 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d  ACH</a> SQL comm
259a0 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20  and that opened 
259b0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
259c0 20 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 65    To control the
259d0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
259e0 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61 6d  ile, use the nam
259f0 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 61  e "main".** or a
25a00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
25a10 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
25a20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
25a30 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  to this routine.
25a40 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69  ** are passed di
25a50 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74  rectly through t
25a60 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  o the second and
25a70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
25a80 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c  s of.** the xFil
25a90 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
25aa0 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
25ab0 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65 43  ue of the xFileC
25ac0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64  ontrol.** method
25ad0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65 74   becomes the ret
25ae0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
25af0 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
25b00 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
25b10 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d  arameter (zDbNam
25b20 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  e) does not matc
25b30 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e  h the name of an
25b40 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  y.** open databa
25b50 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51  se file, then SQ
25b60 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65  LITE_ERROR is re
25b70 74 75 72 6e 65 64 2e 20 20 54 68 69 73 20 65 72  turned.  This er
25b80 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e  ror.** code is n
25b90 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e  ot remembered an
25ba0 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65  d will not be re
25bb0 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74  called by [sqlit
25bc0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a  e3_errcode()].**
25bd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
25be0 6d 73 67 28 29 5d 2e 20 20 54 68 65 20 75 6e 64  msg()].  The und
25bf0 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e  erlying xFileCon
25c00 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68  trol method migh
25c10 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e  t.** also return
25c20 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
25c30 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20  There is no way 
25c40 74 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20 62  to distinguish b
25c50 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63  etween.** an inc
25c60 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61  orrect zDbName a
25c70 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  nd an SQLITE_ERR
25c80 4f 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74  OR return from t
25c90 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
25ca0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
25cb0 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  thod..**.** See 
25cc0 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43  also: [SQLITE_FC
25cd0 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a  NTL_LOCKSTATE].*
25ce0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
25cf0 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74  le_control(sqlit
25d00 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
25d10 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70  *zDbName, int op
25d20 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
25d30 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74   Undo the hack t
25d40 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f  hat converts flo
25d50 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65  ating point type
25d60 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72  s to integer for
25d70 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72  .** builds on pr
25d80 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74  ocessors without
25d90 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
25da0 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64  support..*/.#ifd
25db0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
25dc0 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
25dd0 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e  undef double.#en
25de0 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70  dif..#ifdef __cp
25df0 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e  lusplus.}  /* En
25e00 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e  d of the 'extern
25e10 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23   "C"' block */.#
25e20 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a           endif.#endif.