/ Hex Artifact Content
Login

Artifact b886a911e1e72e3f79fb1d66553ce5c717042267:


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 37 35 20 32 30 30 37 2f  in,v 1.275 2007/
05f0: 31 32 2f 30 35 20 31 38 3a 30 35 3a 31 36 20 64  12/05 18:05:16 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 20 7b  ersion Numbers {
0840: 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F10010}.**.** {F
0850: 31 30 30 31 31 7d 20 54 68 65 20 76 65 72 73 69  10011} The versi
0860: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
0870: 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6e 74   library is cont
0880: 61 69 6e 65 64 20 69 6e 20 74 68 65 20 73 71 6c  ained in the sql
0890: 69 74 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 72  ite3.h.** header
08a0: 20 66 69 6c 65 20 69 6e 20 61 20 23 64 65 66 69   file in a #defi
08b0: 6e 65 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f  ne named SQLITE_
08c0: 56 45 52 53 49 4f 4e 2e 20 20 7b 46 31 30 30 31  VERSION.  {F1001
08d0: 32 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45  2} The SQLITE_VE
08e0: 52 53 49 4f 4e 0a 2a 2a 20 6d 61 63 72 6f 20 72  RSION.** macro r
08f0: 65 73 6f 6c 76 65 73 20 74 6f 20 61 20 73 74 72  esolves to a str
0900: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2a  ing constant..**
0910: 0a 2a 2a 20 7b 46 31 30 30 31 33 7d 20 54 68 65  .** {F10013} The
0920: 20 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20 76   format of the v
0930: 65 72 73 69 6f 6e 20 73 74 72 69 6e 67 20 69 73  ersion string is
0940: 20 22 58 2e 59 2e 5a 22 2c 20 77 68 65 72 65 0a   "X.Y.Z", where.
0950: 2a 2a 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f  ** X is the majo
0960: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
0970: 2c 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72  , Y is the minor
0980: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
0990: 61 6e 64 20 5a 0a 2a 2a 20 69 73 20 74 68 65 20  and Z.** is the 
09a0: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 20  release number. 
09b0: 20 54 68 65 20 58 2e 59 2e 5a 20 6d 69 67 68 74   The X.Y.Z might
09c0: 20 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20   be followed by 
09d0: 22 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61  "alpha" or "beta
09e0: 22 2e 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  "..** For exampl
09f0: 65 20 22 33 2e 31 2e 31 62 65 74 61 22 2e 20 7b  e "3.1.1beta". {
0a00: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 58  END}.**.** The X
0a10: 20 76 61 6c 75 65 20 69 73 20 61 6c 77 61 79 73   value is always
0a20: 20 33 20 69 6e 20 53 51 4c 69 74 65 2e 20 20 54   3 in SQLite.  T
0a30: 68 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20  he X value only 
0a40: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0a50: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0a60: 69 62 69 6c 69 74 79 20 69 73 20 62 72 6f 6b 65  ibility is broke
0a70: 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20  n and we intend 
0a80: 74 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a  to never break.*
0a90: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
0aa0: 61 74 69 62 69 6c 69 74 79 2e 20 20 54 68 65 20  atibility.  The 
0ab0: 59 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61  Y value only cha
0ac0: 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nges when.** the
0ad0: 72 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61  re are major fea
0ae0: 74 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74  ture enhancement
0af0: 73 20 74 68 61 74 20 61 72 65 20 66 6f 72 77 61  s that are forwa
0b00: 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a  rds compatible.*
0b10: 2a 20 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61  * but not backwa
0b20: 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20  rds compatible. 
0b30: 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20   The Z value is 
0b40: 69 6e 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68  incremented with
0b50: 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65  .** each release
0b60: 20 62 75 74 20 72 65 73 65 74 73 20 62 61 63 6b   but resets back
0b70: 20 74 6f 20 30 20 77 68 65 6e 20 59 20 69 73 20   to 0 when Y is 
0b80: 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a  incremented..**.
0b90: 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68 65 20  ** {F10014} The 
0ba0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0bb0: 55 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65  UMBER is an inte
0bc0: 67 65 72 20 77 69 74 68 20 74 68 65 20 76 61 6c  ger with the val
0bd0: 75 65 20 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30  ue .** (X*100000
0be0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e  0 + Y*1000 + Z).
0bf0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f   For example, fo
0c00: 72 20 76 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31  r version "3.1.1
0c10: 62 65 74 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54  beta", .** SQLIT
0c20: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c30: 20 69 73 20 73 65 74 20 74 6f 20 33 30 30 31 30   is set to 30010
0c40: 30 31 2e 20 54 6f 20 64 65 74 65 63 74 20 69 66  01. To detect if
0c50: 20 74 68 65 79 20 61 72 65 20 75 73 69 6e 67 20   they are using 
0c60: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e  .** version 3.1.
0c70: 31 20 6f 72 20 67 72 65 61 74 65 72 20 61 74 20  1 or greater at 
0c80: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2c 20 70 72  compile time, pr
0c90: 6f 67 72 61 6d 73 20 6d 61 79 20 75 73 65 20 74  ograms may use t
0ca0: 68 65 20 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c  he test .** (SQL
0cb0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0cc0: 45 52 3e 3d 33 30 30 31 30 30 31 29 2e 20 7b 45  ER>=3001001). {E
0cd0: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ND}.**.** See al
0ce0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
0cf0: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
0d00: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0d10: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2f  on_number()]..*/
0d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0d30: 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20  VERSION         
0d40: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
0d50: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
0d60: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
0d70: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a  ON-NUMBER--../*.
0d80: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
0d90: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
0da0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 46  rsion Numbers {F
0db0: 31 30 30 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  10020}.**.** {F1
0dc0: 30 30 32 31 7d 20 54 68 65 73 65 20 72 6f 75 74  0021} These rout
0dd0: 69 6e 65 73 20 72 65 74 75 72 6e 20 76 61 6c 75  ines return valu
0de0: 65 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  es equivalent to
0df0: 20 74 68 65 20 68 65 61 64 65 72 20 63 6f 6e 73   the header cons
0e00: 74 61 6e 74 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  tants.** [SQLITE
0e10: 5f 56 45 52 53 49 4f 4e 5d 20 61 6e 64 20 5b 53  _VERSION] and [S
0e20: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0e30: 4d 42 45 52 5d 2e 20 20 7b 45 4e 44 7d 20 54 68  MBER].  {END} Th
0e40: 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
0e50: 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75  d.** by this rou
0e60: 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 6f 6e 6c  tines should onl
0e70: 79 20 62 65 20 64 69 66 66 65 72 65 6e 74 20 66  y be different f
0e80: 72 6f 6d 20 74 68 65 20 68 65 61 64 65 72 20 76  rom the header v
0e90: 61 6c 75 65 73 0a 2a 2a 20 69 66 20 74 68 65 20  alues.** if the 
0ea0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 63  application is c
0eb0: 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 61 6e  ompiled using an
0ec0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
0ed0: 72 20 66 72 6f 6d 20 61 0a 2a 2a 20 64 69 66 66  r from a.** diff
0ee0: 65 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66  erent version of
0ef0: 20 53 51 4c 69 74 65 20 74 68 61 6e 20 6c 69 62   SQLite than lib
0f00: 72 61 72 79 2e 20 20 43 61 75 74 69 6f 75 73 20  rary.  Cautious 
0f10: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
0f20: 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63  t.** include a c
0f30: 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70  heck in their ap
0f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72  plication to ver
0f50: 69 66 79 20 74 68 61 74 20 0a 2a 2a 20 73 71 6c  ify that .** sql
0f60: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
0f70: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
0f80: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
0f90: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  e .** [SQLITE_VE
0fa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
0fb0: 2a 0a 2a 2a 20 7b 46 31 30 30 32 32 7d 20 54 68  *.** {F10022} Th
0fc0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
0fd0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
0fe0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
0ff0: 20 74 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a 20   text of the.** 
1000: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
1010: 20 73 74 72 69 6e 67 2e 20 7b 46 31 30 30 32 33   string. {F10023
1020: 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69  } The sqlite3_li
1030: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74  bversion() funct
1040: 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ion returns.** a
1050: 20 70 6f 69 6e 65 72 20 74 6f 20 74 68 65 20 73   poiner to the s
1060: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1070: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1080: 2e 20 7b 45 4e 44 7d 20 54 68 65 20 66 75 6e 63  . {END} The func
1090: 74 69 6f 6e 0a 2a 2a 20 69 73 20 70 72 6f 76 69  tion.** is provi
10a0: 64 65 64 20 66 6f 72 20 44 4c 4c 20 75 73 65 72  ded for DLL user
10b0: 73 20 77 68 6f 20 63 61 6e 20 6f 6e 6c 79 20 61  s who can only a
10c0: 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 20  ccess functions 
10d0: 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63 6f 6e 73 74  and not.** const
10e0: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
10f0: 44 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  DLL..*/.SQLITE_E
1100: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1110: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1120: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1130: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1140: 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  on(void);.int sq
1150: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1160: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1170: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1180: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1190: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
11a0: 72 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30  readsafe {F10100
11b0: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d  }.**.** {F10101}
11c0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
11d0: 74 75 72 6e 73 20 54 52 55 45 20 28 6e 6f 6e 7a  turns TRUE (nonz
11e0: 65 72 6f 29 20 69 66 20 53 51 4c 69 74 65 20 77  ero) if SQLite w
11f0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1200: 0a 2a 2a 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d  .** all of its m
1210: 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 61  utexes enabled a
1220: 6e 64 20 69 73 20 74 68 75 73 20 74 68 72 65 61  nd is thus threa
1230: 64 73 61 66 65 2e 20 20 7b 46 31 30 31 30 32 7d  dsafe.  {F10102}
1240: 20 49 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 7a   It returns.** z
1250: 65 72 6f 20 69 66 20 74 68 65 20 70 61 72 74 69  ero if the parti
1260: 63 75 6c 61 72 20 62 75 69 6c 64 20 69 73 20 66  cular build is f
1270: 6f 72 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  or single-thread
1280: 65 64 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  ed operation.** 
1290: 6f 6e 6c 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  only. {END}.**.*
12a0: 2a 20 7b 46 31 30 31 30 33 7d 20 52 65 61 6c 6c  * {F10103} Reall
12b0: 79 20 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69  y all this routi
12c0: 6e 65 20 64 6f 65 73 20 69 73 20 72 65 74 75 72  ne does is retur
12d0: 6e 20 74 72 75 65 20 69 66 20 53 51 4c 69 74 65  n true if SQLite
12e0: 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
12f0: 20 77 69 74 68 20 74 68 65 20 2d 44 53 51 4c 49   with the -DSQLI
1300: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1310: 6f 70 74 69 6f 6e 20 61 6e 64 20 66 61 6c 73 65  option and false
1320: 20 69 66 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   if.** compiled 
1330: 77 69 74 68 20 2d 44 53 51 4c 49 54 45 5f 54 48  with -DSQLITE_TH
1340: 52 45 41 44 53 41 46 45 3d 30 2e 20 20 7b 55 31  READSAFE=0.  {U1
1350: 30 31 30 34 7d 20 49 66 20 53 51 4c 69 74 65 20  0104} If SQLite 
1360: 75 73 65 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  uses an.** appli
1370: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6d  cation-defined m
1380: 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 2c 20  utex subsystem, 
1390: 6d 61 6c 6c 6f 63 20 73 75 62 73 79 73 74 65 6d  malloc subsystem
13a0: 2c 20 63 6f 6c 6c 61 74 69 6e 67 0a 2a 2a 20 73  , collating.** s
13b0: 65 71 75 65 6e 63 65 2c 20 56 46 53 2c 20 53 51  equence, VFS, SQ
13c0: 4c 20 66 75 6e 63 74 69 6f 6e 2c 20 70 72 6f 67  L function, prog
13d0: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 2c 20 63  ress callback, c
13e0: 6f 6d 6d 69 74 20 68 6f 6f 6b 2c 0a 2a 2a 20 65  ommit hook,.** e
13f0: 78 74 65 6e 73 69 6f 6e 2c 20 6f 72 20 6f 74 68  xtension, or oth
1400: 65 72 20 61 63 63 65 73 73 6f 72 69 65 73 20 61  er accessories a
1410: 6e 64 20 74 68 65 73 65 20 61 64 64 2d 6f 6e 73  nd these add-ons
1420: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 74 68 72 65   are not.** thre
1430: 61 64 73 61 66 65 2c 20 74 68 65 6e 20 63 6c 65  adsafe, then cle
1440: 61 72 6c 79 20 74 68 65 20 63 6f 6d 62 69 6e 61  arly the combina
1450: 74 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 62 65  tion will not be
1460: 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a 20 65   threadsafe.** e
1470: 69 74 68 65 72 2e 20 20 7b 45 4e 44 7d 20 48 65  ither.  {END} He
1480: 6e 63 65 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  nce, this routin
1490: 65 20 6e 65 76 65 72 20 72 65 70 6f 72 74 73 20  e never reports 
14a0: 74 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79  that the library
14b0: 0a 2a 2a 20 69 73 20 67 75 61 72 61 6e 74 65 65  .** is guarantee
14c0: 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
14d0: 66 65 2c 20 6f 6e 6c 79 20 77 68 65 6e 20 69 74  fe, only when it
14e0: 20 69 73 20 67 75 61 72 61 6e 74 65 65 64 20 6e   is guaranteed n
14f0: 6f 74 0a 2a 2a 20 74 6f 20 62 65 2e 0a 2a 2f 0a  ot.** to be..*/.
1500: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
1510: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
1520: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1530: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1540: 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32 30 30  on Handle {F1200
1550: 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  0}.**.** Each op
1560: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
1570: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
1580: 64 20 62 79 20 70 6f 69 6e 74 65 72 20 74 6f 20  d by pointer to 
1590: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15a0: 68 65 0a 2a 2a 20 6f 70 61 71 75 65 20 73 74 72  he.** opaque str
15b0: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
15c0: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
15d0: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
15e0: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
15f0: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
1600: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
1610: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1620: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1630: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1640: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1650: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
1660: 6f 6e 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61  onstructors.** a
1670: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
1680: 65 28 29 5d 20 69 73 20 69 74 73 20 64 65 73 74  e()] is its dest
1690: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61  ructor.  There a
16a0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e  re many other in
16b0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 28 73 75 63  terfaces.** (suc
16c0: 68 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  h as [sqlite3_pr
16d0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
16e0: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
16f0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
1700: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1710: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
1720: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
1730: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
1740: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e   this.** object.
1750: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1760: 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74  ct sqlite3 sqlit
1770: 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e3;.../*.** CAPI
1780: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1790: 65 67 65 72 20 54 79 70 65 73 20 7b 46 31 30 32  eger Types {F102
17a0: 30 30 7d 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  00}.**.** Becaus
17b0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
17c0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
17d0: 20 74 6f 20 73 70 65 63 69 66 79 20 73 75 63 68   to specify such
17e0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
17f0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
1800: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
1810: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
1820: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 20 7b  d integers..** {
1830: 46 31 30 32 30 31 7d 20 54 68 65 20 73 71 6c 69  F10201} The sqli
1840: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
1850: 69 74 65 33 5f 69 6e 74 36 34 20 74 79 70 65 73  ite3_int64 types
1860: 20 73 70 65 63 69 66 79 20 61 0a 2a 2a 20 36 34   specify a.** 64
1870: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1880: 67 65 72 2e 20 7b 46 31 30 32 30 32 7d 20 54 68  ger. {F10202} Th
1890: 65 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  e sqlite_uint64 
18a0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
18b0: 69 6e 74 36 34 20 74 79 70 65 73 20 73 70 65 63  int64 types spec
18c0: 69 66 79 20 61 20 36 34 2d 62 69 74 20 75 6e 73  ify a 64-bit uns
18d0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 20 7b  igned integer. {
18e0: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  END}.**.** The s
18f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
1900: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
1910: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
1920: 64 20 74 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69  d type.** defini
1930: 74 69 6f 6e 73 2e 20 20 54 68 65 20 73 71 6c 69  tions.  The sqli
1940: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
1950: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
1960: 20 61 72 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65   are.** supporte
1970: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1980: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
1990: 6c 79 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ly..*/.#ifdef SQ
19a0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
19b0: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
19c0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
19d0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
19e0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
19f0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
1a00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1a10: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
1a20: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
1a30: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
1a40: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
1a50: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1a60: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1a70: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
1a80: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
1a90: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
1aa0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
1ab0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1ac0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
1ad0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
1ae0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
1af0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
1b00: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
1b10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
1b20: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
1b30: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
1b40: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
1b50: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
1b60: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
1b70: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
1b80: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
1b90: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
1ba0: 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20  point.*/.#ifdef 
1bb0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
1bc0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
1bd0: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
1be0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
1bf0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c00: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
1c10: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b  ase Connection {
1c20: 46 31 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12010}.**.** {F
1c30: 31 32 30 31 30 7d 20 43 61 6c 6c 20 74 68 69 73  12010} Call this
1c40: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
1c50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
1c60: 72 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73  ructure that was
1c70: 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20   .** previously 
1c80: 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
1c90: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1ca0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1cb0: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
1cc0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e  e3_open_v2()] an
1cd0: 64 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  d the correspond
1ce0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 77 69 6c  ing database wil
1cf0: 6c 20 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 20  l by.** closed. 
1d00: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  {END}.**.** {F12
1d10: 30 31 31 7d 20 41 6c 6c 20 53 51 4c 20 73 74 61  011} All SQL sta
1d20: 74 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64  tements prepared
1d30: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d40: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d50: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d60: 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73  pare16_v2()] mus
1d70: 74 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75  t be destroyed u
1d80: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1d90: 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66  nalize()].** bef
1da0: 6f 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ore this routine
1db0: 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65   is called. Othe
1dc0: 72 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55  rwise, SQLITE_BU
1dd0: 53 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  SY is returned a
1de0: 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
1df0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65  se connection re
1e00: 6d 61 69 6e 73 20 6f 70 65 6e 2e 20 7b 45 4e 44  mains open. {END
1e10: 7d 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 32 7d  }.**.** {U12012}
1e20: 20 50 61 73 73 69 6e 67 20 74 68 69 73 20 72 6f   Passing this ro
1e30: 75 74 69 6e 65 20 61 20 64 61 74 61 62 61 73 65  utine a database
1e40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1e50: 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
1e60: 6e 0a 2a 2a 20 63 6c 6f 73 65 64 20 72 65 73 75  n.** closed resu
1e70: 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
1e80: 20 62 65 68 61 76 69 6f 72 2e 20 7b 55 31 32 30   behavior. {U120
1e90: 31 33 7d 20 49 66 20 6f 74 68 65 72 20 69 6e 74  13} If other int
1ea0: 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a 2a 20  erfaces that.** 
1eb0: 72 65 66 65 72 65 6e 63 65 20 74 68 65 20 73 61  reference the sa
1ec0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1ed0: 65 63 74 69 6f 6e 20 61 72 65 20 70 65 6e 64 69  ection are pendi
1ee0: 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20 74 68  ng (either in th
1ef0: 65 0a 2a 2a 20 73 61 6d 65 20 74 68 72 65 61 64  e.** same thread
1f00: 20 6f 72 20 69 6e 20 64 69 66 66 65 72 65 6e 74   or in different
1f10: 20 74 68 72 65 61 64 73 29 20 77 68 65 6e 20 74   threads) when t
1f20: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
1f30: 61 6c 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e 20 74  alled,.** then t
1f40: 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1f50: 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 73 20  ndefined and is 
1f60: 61 6c 6d 6f 73 74 20 63 65 72 74 61 69 6e 6c 79  almost certainly
1f70: 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
1f80: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
1f90: 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a  se(sqlite3 *);..
1fa0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
1fb0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
1fc0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
1fd0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
1fe0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
1ff0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
2000: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
2010: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
2020: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
2030: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
2040: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
2050: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
2060: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
2070: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2080: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
2090: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
20a0: 63 65 20 7b 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a  ce {F12100}.**.*
20b0: 2a 20 7b 46 31 32 31 30 31 7d 20 54 68 65 20 73  * {F12101} The s
20c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
20d0: 74 65 72 66 61 63 65 20 65 76 61 6c 75 61 74 65  terface evaluate
20e0: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 0a  s zero or more .
20f0: 2a 2a 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ** UTF-8 encoded
2100: 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  , semicolon-sepa
2110: 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 73 74 61  rated SQL.** sta
2120: 74 65 6d 65 6e 74 73 20 70 72 6f 76 69 64 65 64  tements provided
2130: 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 20 61   as its second a
2140: 72 67 75 6d 65 6e 74 2e 20 20 7b 46 31 32 31 30  rgument.  {F1210
2150: 32 7d 20 54 68 65 20 53 51 4c 0a 2a 2a 20 73 74  2} The SQL.** st
2160: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
2170: 6c 75 61 74 65 64 20 69 6e 20 74 68 65 20 63 6f  luated in the co
2180: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 64 61 74  ntext of the dat
2190: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21a0: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 69 6e 20  .** provided in 
21b0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
21c0: 6e 74 2e 0a 2a 2a 20 7b 46 31 32 31 30 33 7d 20  nt..** {F12103} 
21d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
21e0: 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65 20  re prepared one 
21f0: 62 79 20 6f 6e 65 20 75 73 69 6e 67 0a 2a 2a 20  by one using.** 
2200: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2210: 28 29 5d 20 6f 72 20 74 68 65 20 65 71 75 69 76  ()] or the equiv
2220: 61 6c 65 6e 74 2c 20 65 76 61 6c 75 61 74 65 64  alent, evaluated
2230: 0a 2a 2a 20 75 73 69 6e 67 20 6f 6e 65 20 6f 72  .** using one or
2240: 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2250: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2260: 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 0a   then destroyed.
2270: 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2280: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 20 7b  3_finalize()]. {
2290: 46 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  F12104} The retu
22a0: 72 6e 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 73  rn value of.** s
22b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
22c0: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6c   SQLITE_OK if al
22d0: 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  l SQL statement 
22e0: 72 75 6e 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  run.** successfu
22f0: 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  lly..**.** {F121
2300: 30 35 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f  05} If one or mo
2310: 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  re of the SQL st
2320: 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20  atements handed 
2330: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
2340: 65 63 28 29 20 61 72 65 20 71 75 65 72 69 65 73  ec() are queries
2350: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61  , then.** the ca
2360: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2370: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2380: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2390: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  s.** invoked onc
23a0: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
23b0: 66 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75  f the query resu
23c0: 6c 74 2e 20 7b 46 31 32 31 30 36 7d 0a 2a 2a 20  lt. {F12106}.** 
23d0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
23e0: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
23f0: 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20 74 68  ro value then th
2400: 65 20 71 75 65 72 79 0a 2a 2a 20 69 73 20 61 62  e query.** is ab
2410: 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73 65  orted, all subse
2420: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
2430: 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69 70  ents.** are skip
2440: 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c 69  ped and the sqli
2450: 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63 74  te3_exec() funct
2460: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
2470: 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
2480: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 54  **.** {F12107} T
2490: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
24a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
24b0: 28 29 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  () is an arbitra
24c0: 72 79 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ry pointer.** th
24d0: 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  at is passed thr
24e0: 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
24f0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73  back function as
2500: 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
2510: 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  eter..**.** {F12
2520: 31 30 38 7d 20 54 68 65 20 32 6e 64 20 70 61 72  108} The 2nd par
2530: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
2540: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2550: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2560: 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  .** columns in t
2570: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e  he query result.
2580: 20 20 7b 46 31 32 31 30 39 7d 20 54 68 65 20 33    {F12109} The 3
2590: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
25a0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
25b0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
25c0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
25d0: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 76  gs holding the v
25e0: 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63  alues for each c
25f0: 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74 72  olumn.** as extr
2600: 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  acted using [sql
2610: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2620: 28 29 5d 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  ()].  NULL value
2630: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 0a  s in the result.
2640: 2a 2a 20 73 65 74 20 72 65 73 75 6c 74 20 69 6e  ** set result in
2650: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2660: 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
2670: 65 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  e are in their U
2680: 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 72  TF-8.** string r
2690: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e 20 7b  epresentation. {
26a0: 46 31 32 31 31 30 7d 0a 2a 2a 20 54 68 65 20 34  F12110}.** The 4
26b0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26c0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
26d0: 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69  an array of stri
26e0: 6e 67 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ngs.** obtained 
26f0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2700: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
2710: 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65  d holding.** the
2720: 20 6e 61 6d 65 73 20 6f 66 20 65 61 63 68 20 63   names of each c
2730: 6f 6c 75 6d 6e 2c 20 61 6c 73 6f 20 69 6e 20 55  olumn, also in U
2740: 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  TF-8..**.** {F12
2750: 31 31 30 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  110} The callbac
2760: 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
2770: 65 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72  e NULL, even for
2780: 20 71 75 65 72 69 65 73 2e 20 20 41 20 4e 55 4c   queries.  A NUL
2790: 4c 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  L.** callback is
27a0: 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e 20 20   not an error.  
27b0: 49 74 20 6a 75 73 74 20 6d 65 61 6e 73 20 74 68  It just means th
27c0: 61 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  at no callback.*
27d0: 2a 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  * will be invoke
27e0: 64 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  d. .**.** {F1211
27f0: 32 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  2} If an error o
2800: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
2810: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
2820: 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 68 65  g the SQL.** the
2830: 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
2840: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
2850: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
2860: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
2870: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2880: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 2a 65  malloc()] and *e
2890: 72 72 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f  rrmsg is made to
28a0: 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d   point to that m
28b0: 65 73 73 61 67 65 0a 2a 2a 20 61 73 73 75 6d 69  essage.** assumi
28c0: 6e 67 20 65 72 72 6d 73 67 20 69 73 20 6e 6f 74  ng errmsg is not
28d0: 20 4e 55 4c 4c 2e 20 20 7b 55 31 32 31 31 33 7d   NULL.  {U12113}
28e0: 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
28f0: 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70  ction.** is resp
2900: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
2910: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 75  ing the memory u
2920: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
2930: 65 65 28 29 5d 2e 0a 2a 2a 20 7b 46 31 32 31 31  ee()]..** {F1211
2940: 34 7d 20 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55  4} If errmsg==NU
2950: 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f  LL, then no erro
2960: 72 20 6d 65 73 73 61 67 65 20 69 73 20 65 76 65  r message is eve
2970: 72 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  r written..**.**
2980: 20 7b 46 31 32 31 31 35 7d 20 54 68 65 20 72 65   {F12115} The re
2990: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 69 73  turn value is is
29a0: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68   SQLITE_OK if th
29b0: 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72  ere are no error
29c0: 73 20 61 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74  s and.** some ot
29d0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  her [SQLITE_OK |
29e0: 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 20 69 66   return code] if
29f0: 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
2a00: 6f 72 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72  or.  .** The par
2a10: 74 69 63 75 6c 61 72 20 72 65 74 75 72 6e 20 76  ticular return v
2a20: 61 6c 75 65 20 64 65 70 65 6e 64 73 20 6f 6e 20  alue depends on 
2a30: 74 68 65 20 74 79 70 65 20 6f 66 20 65 72 72 6f  the type of erro
2a40: 72 2e 20 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  r.  {END}.*/.int
2a50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
2a60: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
2a70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a80: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
2a90: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
2aa0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ab0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
2ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ad0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
2ae0: 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  luted */.  int (
2af0: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
2b00: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
2b10: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
2b20: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
2b30: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
2b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b50: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
2b60: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
2b70: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
2b80: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
2b90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ba0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
2bb0: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
2bc0: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2bd0: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
2be0: 6f 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a  odes {F10210}.**
2bf0: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2c00: 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  E_OK.**.** Many 
2c10: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
2c20: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
2c30: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
2c40: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
2c50: 6e 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f 72  n.** above in or
2c60: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73  der to indicates
2c70: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
2c80: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ure..**.** {F102
2c90: 31 31 7d 20 54 68 65 20 72 65 73 75 6c 74 20 63  11} The result c
2ca0: 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 20 74  odes above are t
2cb0: 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74  he only ones ret
2cc0: 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
2cd0: 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 75 6c  in its.** defaul
2ce0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e  t configuration.
2cf0: 20 7b 46 31 30 32 31 32 7d 20 48 6f 77 65 76 65   {F10212} Howeve
2d00: 72 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  r, the.** [sqlit
2d10: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
2d20: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 20  lt_codes()] API 
2d30: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73  can be used to s
2d40: 65 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  et a database.**
2d50: 20 63 6f 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72   connectoin to r
2d60: 65 74 75 72 6e 20 6d 6f 72 65 20 64 65 74 61 69  eturn more detai
2d70: 6c 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  led result codes
2d80: 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65  . {END}.**.** Se
2d90: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
2da0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
2db0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2dc0: 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e  es].**.*/.#defin
2dd0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
2de0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
2df0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
2e00: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
2e10: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
2e20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e30: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
2e40: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
2e50: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
2e60: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
2e70: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
2e80: 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44   2   /* NOT USED
2e90: 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  . Internal logic
2ea0: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
2eb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2ec0: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
2ed0: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
2ee0: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
2ef0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f00: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
2f10: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
2f20: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
2f30: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
2f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
2f50: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
2f60: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
2f70: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
2f80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
2f90: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
2fa0: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
2fb0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
2fc0: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
2fd0: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
2fe0: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
2ff0: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
3000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
3010: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
3020: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
3030: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
3040: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
3050: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
3060: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
3070: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
3080: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
3090: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
30a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
30b0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
30c0: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
30d0: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
30e0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
30f0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
3100: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
3110: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
3120: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
3130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3140: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
3150: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61   /* NOT USED. Ta
3160: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f  ble or record no
3170: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69  t found */.#defi
3180: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
3190: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
31a0: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
31b0: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
31c0: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
31d0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
31e0: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
31f0: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
3200: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
3210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3220: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
3230: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44    /* NOT USED. D
3240: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
3250: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
3260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
3270: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
3280: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
3290: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
32a0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
32b0: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
32c0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
32d0: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
32e0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
32f0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
3300: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
3310: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
3320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3330: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
3340: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
3350: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
3360: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
3370: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
3380: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
3390: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
33a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33b0: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
33c0: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
33d0: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
33e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33f0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
3400: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
3410: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
3420: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
3430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
3440: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
3450: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
3460: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
3470: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
3480: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
3490: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
34a0: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
34b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
34c0: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
34d0: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
34e0: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
34f0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
3500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
3510: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
3520: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
3530: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
3540: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
3550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
3560: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
3570: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
3580: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
3590: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
35a0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
35b0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
35c0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
35d0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
35e0: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
35f0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
3600: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
3610: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
3620: 6f 64 65 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a  odes {F10220}.**
3630: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
3640: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
3650: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
3660: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
3670: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
3680: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
3690: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
36a0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
36b0: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
36c0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
36d0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
36e0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
36f0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
3700: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
3710: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
3720: 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73 20  oblems as users 
3730: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
3740: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
3750: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
3760: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
3770: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
3780: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
3790: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
37a0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
37b0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
37c0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
37d0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
37e0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
37f0: 65 72 72 6f 72 73 2e 20 7b 46 31 30 32 32 31 7d  errors. {F10221}
3800: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3810: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3820: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
3830: 65 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64  ed.** for each d
3840: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3850: 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  on using the [sq
3860: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
3870: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a  esult_codes()].*
3880: 2a 20 41 50 49 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  * API. {END}.** 
3890: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
38a0: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
38b0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
38c0: 61 72 65 20 6c 69 73 74 65 64 20 61 62 6f 76 65  are listed above
38d0: 2e 0a 2a 2a 20 57 65 20 65 78 70 65 63 74 20 74  ..** We expect t
38e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
38f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3900: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
3910: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
3920: 20 7b 55 31 30 34 32 32 7d 20 53 6f 66 74 77 61   {U10422} Softwa
3930: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74  re that uses ext
3940: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3950: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74  es should expect
3960: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72  .** to see new r
3970: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66  esult codes in f
3980: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
3990: 66 20 53 51 4c 69 74 65 2e 20 7b 45 4e 44 7d 0a  f SQLite. {END}.
39a0: 2a 2a 20 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20  ** .** {F10223} 
39b0: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
39c0: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
39d0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c  d result code al
39e0: 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  ways contains.**
39f0: 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61   a related prima
3a00: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  ry result code a
3a10: 73 20 61 20 70 72 65 66 69 78 2e 20 7b 46 31 30  s a prefix. {F10
3a20: 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73  224} Primary res
3a30: 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 63 6f 6e  ult.** codes con
3a40: 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f  tain a single "_
3a50: 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 7b 46  " character.  {F
3a60: 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20  10225} Extended 
3a70: 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20  result codes.** 
3a80: 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d  contain two or m
3a90: 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  ore "_" characte
3aa0: 72 73 2e 20 7b 46 31 30 32 32 36 7d 20 54 68 65  rs. {F10226} The
3ab0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
3ac0: 66 20 61 6e 0a 2a 2a 20 65 78 74 65 6e 64 65 64  f an.** extended
3ad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61 6e   result code can
3ae0: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
3af0: 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   its.** correspo
3b00: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
3b10: 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61 73  sult code by mas
3b20: 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f 77  king off the low
3b30: 65 72 20 38 20 62 79 74 65 73 2e 20 7b 45 4e 44  er 8 bytes. {END
3b40: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  }.**.** The SQLI
3b50: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
3b60: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
3b70: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
3b80: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
3b90: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
3ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3bb0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
3bc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3bd0: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
3be0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3bf0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28  _SHORT_READ    (
3c00: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3c10: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
3c20: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54  QLITE_IOERR_WRIT
3c30: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
3c40: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
3c50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3c60: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
3c70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3c80: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
3c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ca0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
3cb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3cc0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
3cd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
3ce0: 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c 49  NCATE      (SQLI
3cf0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38  TE_IOERR | (6<<8
3d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3d10: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20  E_IOERR_FSTAT   
3d20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3d30: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
3d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3d50: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
3d60: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3d70: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
3d80: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
3d90: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  LOCK        (SQL
3da0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
3db0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3dc0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
3dd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3de0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a  OERR | (10<<8)).
3df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3e00: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20  OERR_BLOCKED    
3e10: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3e20: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
3e30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3e40: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 28  _NOMEM         (
3e50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3e60: 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  12<<8))../*.** C
3e70: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
3e80: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
3e90: 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30 7d  rations {F10230}
3ea0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 33 31 7d 20  .**.** {F10231} 
3eb0: 53 6f 6d 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  Some combination
3ec0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 20 62 69   of the these bi
3ed0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 75 73 65  t values are use
3ee0: 64 20 61 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  d as the.** thir
3ef0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3f00: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
3f10: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
3f20: 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75 72 74 68  and.** as fourth
3f30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3f40: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
3f50: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
3f60: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
3f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f80: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
3f90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
3fc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
3ff0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
4000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4010: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
4020: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
4050: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
4060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4070: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
4080: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
4090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40a0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
40b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
40c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40d0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
40e0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
40f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4100: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
4110: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
4120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4130: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
4140: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
4150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4160: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
4170: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
4180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4190: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
41a0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
41b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
41c0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
41d0: 65 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30  eristics {F10240
41e0: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 34 31 7d  }.**.** {F10241}
41f0: 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61   The xDeviceCapa
4200: 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20  bilities method 
4210: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
4220: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
4230: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
4240: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
4250: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
4260: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  e these.** bit v
4270: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
4280: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
4290: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
42a0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
42b0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
42c0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
42d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
42e0: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
42f0: 6f 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  o. {END}.**.** {
4300: 46 31 30 32 34 32 7d 20 54 68 65 20 53 51 4c 49  F10242} The SQLI
4310: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
4320: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
4330: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
4340: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
4350: 65 20 61 74 6f 6d 69 63 2e 20 20 7b 46 31 30 32  e atomic.  {F102
4360: 34 33 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 49  43} The SQLITE_I
4370: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
4380: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
4390: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
43a0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
43b0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
43c0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
43d0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
43e0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
43f0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
4400: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
4410: 63 2e 20 20 7b 46 31 30 32 34 34 7d 20 54 68 65  c.  {F10244} The
4420: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
4430: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
4440: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
4450: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
4460: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
4470: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
4480: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
4490: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
44a0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
44b0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
44c0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
44d0: 64 2e 20 20 7b 46 31 30 32 34 35 7d 20 54 68 65  d.  {F10245} The
44e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
44f0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
4500: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
4510: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
4520: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
4530: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
4540: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
4550: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65  xWrite()..*/.#de
4560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4570: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
4580: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
4590: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
45a0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
45b0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
45c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
45d0: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
45e0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
45f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4600: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
4610: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
4620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4630: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
4640: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
4650: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4660: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
4670: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
4680: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4690: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
46a0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
46b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
46c0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
46d0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
46e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
46f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
4700: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
4710: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4720: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
4730: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
4740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4750: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
4760: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a    0x00000400../*
4770: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
4780: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
4790: 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a  s {F10250}.**.**
47a0: 20 7b 46 31 30 32 35 31 7d 20 53 51 4c 69 74 65   {F10251} SQLite
47b0: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
47c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
47d0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
47e0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
47f0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
4800: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
4810: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
4820: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
4830: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
4840: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
4850: 20 7b 45 4e 44 7d 0a 2a 2f 0a 23 64 65 66 69 6e   {END}.*/.#defin
4860: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
4870: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
4880: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4890: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
48a0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
48b0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
48c0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
48d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
48e0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
48f0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
4900: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
4910: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
4920: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
4930: 79 70 65 20 46 6c 61 67 73 20 7b 46 31 30 32 36  ype Flags {F1026
4940: 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 31  0}.**.** {F10261
4950: 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
4960: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
4970: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
4980: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
4990: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
49a0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
49b0: 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 74 68  ion of the.** th
49c0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
49d0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
49e0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
49f0: 20 7b 46 31 30 32 36 32 7d 20 57 68 65 6e 20 74   {F10262} When t
4a00: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
4a10: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
4a20: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
4a30: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
4a40: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
4a50: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
4a60: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
4a70: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
4a80: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
4a90: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 7b  ot be flushed. {
4aa0: 46 31 30 32 36 33 7d 20 54 68 65 20 53 51 4c 49  F10263} The SQLI
4ab0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d  TE_SYNC_NORMAL m
4ac0: 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20  eans .** to use 
4ad0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
4ae0: 65 6d 61 6e 74 69 63 73 2e 20 7b 46 31 30 32 36  emantics. {F1026
4af0: 34 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  4} The SQLITE_SY
4b00: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
4b10: 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ns .** to use Ma
4b20: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
4b30: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
4b40: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
4b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4b60: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
4b70: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
4b80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
4b90: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
4bc0: 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a     0x00010.../*.
4bd0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
4be0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
4bf0: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31  ile Handle {F111
4c00: 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10}.**.** An [sq
4c10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
4c20: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
4c30: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
4c40: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
4c50: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
4c60: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
4c70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
4c80: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
4c90: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
4ca0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
4cb0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
4cc0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
4cd0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
4ce0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
4cf0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
4d00: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
4d10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
4d20: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
4d30: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
4d40: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
4d50: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
4d60: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
4d70: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
4d80: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
4d90: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
4da0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
4db0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
4dc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
4dd0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
4de0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
4df0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
4e00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
4e10: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
4e20: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
4e30: 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a  Object {F11120}.
4e40: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
4e50: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
4e60: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
4e70: 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69  en method contai
4e80: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  ns a pointer to.
4e90: 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** an instance o
4ea0: 66 20 74 68 65 20 74 68 69 73 20 6f 62 6a 65 63  f the this objec
4eb0: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
4ec0: 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d  defines the.** m
4ed0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
4ee0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
4ef0: 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73  perations agains
4f00: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  t the open file.
4f10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
4f20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
4f30: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
4f40: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
4f50: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
4f60: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
4f70: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
4f80: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
4f90: 66 73 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20  fsync()..*  The 
4fa0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
4fb0: 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c   an.** OS-X styl
4fc0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
4fd0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
4fe0: 41 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  A flag may be OR
4ff0: 65 64 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69  ed in to.** indi
5000: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
5010: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
5020: 69 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  ile and not its 
5030: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
5040: 65 0a 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20  e.** synced..** 
5050: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
5060: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
5070: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5080: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
5090: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
50a0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
50b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
50c0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
50d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
50e0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
50f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5100: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
5110: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5120: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
5130: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
5140: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
5150: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
5160: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
5170: 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78  lock.  .** The x
5180: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
5190: 6b 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73  k() method looks
51a0: 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e  .** to see if an
51b0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
51c0: 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e  ction, either in
51d0: 20 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73   this.** process
51e0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
51f0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
5200: 6c 64 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45  lding an RESERVE
5210: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
5220: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
5230: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
5240: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
5250: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
5260: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
5270: 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a  e if not..** .**
5280: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
5290: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
52a0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
52b0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
52c0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
52d0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
52e0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
52f0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
5300: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
5310: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
5320: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
5330: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
5340: 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e  rgument.** is an
5350: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
5360: 20 20 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20     The third.** 
5370: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
5380: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68  neric pointer wh
5390: 69 63 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ich is intended 
53a0: 74 6f 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a  to be a pointer.
53b0: 2a 2a 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  ** to a structur
53c0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
53d0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
53e0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
53f0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
5400: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
5410: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
5420: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
5430: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
5440: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
5450: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
5460: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
5470: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
5480: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
5490: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
54a0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
54b0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
54c0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
54d0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
54e0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
54f0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
5500: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
5510: 73 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  s opcodes less t
5520: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
5530: 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b  own use. .** A [
5540: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
5550: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
5560: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
5570: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
5580: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
5590: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
55a0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
55b0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
55c0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
55d0: 73 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  s .** greater th
55e0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
55f0: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a  conflicts..**.**
5600: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
5610: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
5620: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
5630: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
5640: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
5650: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
5660: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
5670: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
5680: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
5690: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
56a0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
56b0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
56c0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
56d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
56e0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
56f0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
5700: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
5710: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
5720: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
5730: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
5740: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
5750: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5760: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5770: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
5780: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
5790: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
57a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
57b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
57c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
57d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
57e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
57f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
5800: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5810: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5820: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
5830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5840: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
5850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5860: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
5870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5880: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
5890: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
58a0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
58b0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
58c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
58d0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
58e0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
58f0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
5900: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5910: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5920: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5930: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5940: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5950: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5960: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5970: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5980: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5990: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
59a0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
59b0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
59d0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
59e0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
59f0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5a00: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5a10: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5a20: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5a30: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5a40: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5a50: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5a60: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5a70: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5a80: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5a90: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5aa0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5ab0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ac0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5ad0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5ae0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5af0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
5b00: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
5b10: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
5b20: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
5b30: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5b40: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
5b50: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
5b60: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
5b70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
5b80: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
5b90: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
5ba0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
5bb0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
5bc0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
5bd0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
5be0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
5bf0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
5c00: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
5c10: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
5c20: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
5c30: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
5c40: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
5c50: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
5c60: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
5c70: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
5c80: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
5c90: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
5ca0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
5cb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
5cc0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
5cd0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
5ce0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
5cf0: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
5d00: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
5d10: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
5d20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
5d30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
5d40: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
5d50: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
5d60: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
5d70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
5d80: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
5d90: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
5da0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
5db0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
5dc0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
5dd0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
5de0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
5df0: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
5e00: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
5e10: 65 73 20 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a  es {F11310}.**.*
5e20: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
5e30: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
5e40: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
5e50: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
5e60: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
5e70: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5e80: 20 6f 62 6a 65 63 74 20 61 6e 64 20 74 6f 20 74   object and to t
5e90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
5ea0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
5eb0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
5ec0: 7b 46 31 31 33 31 31 7d 20 54 68 65 20 5b 53 51  {F11311} The [SQ
5ed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
5ee0: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
5ef0: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
5f00: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
5f10: 6f 64 65 20 63 61 73 65 73 20 74 68 65 20 78 46  ode cases the xF
5f20: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
5f30: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
5f40: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
5f50: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
5f60: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
5f70: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
5f80: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
5f90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
5fa0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
5fb0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5fc0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
5fd0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
5fe0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
5ff0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
6000: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
6010: 20 7b 46 31 31 33 31 32 7d 20 54 68 69 73 20 63   {F11312} This c
6020: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
6030: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
6040: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
6050: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
6060: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
6070: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
6080: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
6090: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
60a0: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f  TATE        1../
60b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
60c0: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 46 31 37  utex Handle {F17
60d0: 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  110}.**.** The m
60e0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
60f0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6100: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6110: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6120: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6130: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
6140: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
6150: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
6160: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
6170: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
6180: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
6190: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
61a0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
61b0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
61c0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
61d0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
61e0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
61f0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6200: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6210: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6220: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6230: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
6240: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6250: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
6260: 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a  t {F11140}.**.**
6270: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
6280: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
6290: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
62a0: 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
62b0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
62c0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
62d0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
62e0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
62f0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
6300: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
6310: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
6320: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
6330: 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20 66  * The iVersion f
6340: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
6350: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
6360: 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72 65  arger for future
6370: 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
6380: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6390: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
63a0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
63b0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
63c0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
63d0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
63e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
63f0: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
6400: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
6410: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
6420: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
6430: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
6440: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
6450: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
6460: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
6470: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
6480: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
6490: 67 69 73 74 65 72 65 64 20 76 66 73 20 6d 6f 64  gistered vfs mod
64a0: 75 6c 65 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ules are kept on
64b0: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
64c0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
64d0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
64e0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
64f0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
6500: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
6510: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
6520: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
6530: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
6540: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
6550: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
6560: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
6570: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
6580: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a  hes the list..**
6590: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
65a0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
65b0: 66 69 65 6c 64 73 20 69 6e 20 74 68 65 20 73 71  fields in the sq
65c0: 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73 74  lite3_vfs .** st
65d0: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
65e0: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
65f0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
6600: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
6610: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
6620: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
6630: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
6640: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
6650: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
6660: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
6670: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
6680: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
6690: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
66a0: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
66b0: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
66c0: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
66d0: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
66e0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
66f0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
6700: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
6710: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
6720: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
6730: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
6740: 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68  ill guarantee th
6750: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
6760: 20 73 74 72 69 6e 67 20 70 61 73 73 65 64 20 74   string passed t
6770: 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73 20  o.** xOpen() is 
6780: 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65 20  a full pathname 
6790: 61 73 20 67 65 6e 65 72 61 74 65 64 20 62 79 20  as generated by 
67a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
67b0: 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  and.** that the 
67c0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
67d0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
67e0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
67f0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
6800: 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   So the [sqlite3
6810: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72 65  _file] can store
6820: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
6830: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
6840: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
6850: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
6860: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
6870: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  on..**.** The fl
6880: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
6890: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 63 6f 70  xOpen() is a cop
68a0: 79 20 6f 66 20 74 68 65 20 66 6c 61 67 73 20 61  y of the flags a
68b0: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
68c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68d0: 5d 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  ].  If [sqlite3_
68e0: 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
68f0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 0a 2a 2a  te3_open16()].**
6900: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
6910: 6c 61 67 73 20 69 73 20 5b 53 51 4c 49 54 45 5f  lags is [SQLITE_
6920: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
6930: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
6940: 52 45 41 54 45 5d 2e 0a 2a 2a 20 49 66 20 78 4f  REATE]..** If xO
6950: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
6960: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
6970: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
6980: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
6990: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
69a0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
69b0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
69c0: 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20 73  lags may be.** s
69d0: 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74  et..** .** SQLit
69e0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
69f0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
6a00: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
6a10: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
6a20: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
6a30: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
6a40: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a 20   opened:.** .** 
6a50: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
6a60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6a70: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
6a80: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6a90: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
6aa0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
6ab0: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
6ac0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
6ad0: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
6ae0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
6af0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
6b00: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
6b10: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
6b20: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
6b30: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6b40: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  URNAL].** </ul>.
6b50: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
6b60: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
6b70: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
6b80: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
6b90: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
6ba0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
6bb0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
6bc0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
6bd0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
6be0: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
6bf0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
6c00: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c 20  ry or rollback, 
6c10: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
6c20: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
6c30: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
6c40: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
6c50: 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a 2a  s journal are.**
6c60: 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20 20   also a no-op.  
6c70: 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  Any attempt to r
6c80: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
6c90: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49 4f  return SQLITE_IO
6ca0: 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20 69  ERR..** Or the i
6cb0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
6cc0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
6cd0: 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  e a database fil
6ce0: 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f 69  e will.** be doi
6cf0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
6d00: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
6d10: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
6d20: 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e 64  dom order.** and
6d30: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
6d40: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
6d50: 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  ingly..** .** SQ
6d60: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
6d70: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
6d80: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
6d90: 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 6d  o the xOpen.** m
6da0: 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ethod:.** .** <u
6db0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6dc0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
6dd0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
6de0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
6df0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
6e00: 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  ** .** The [SQLI
6e10: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
6e20: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
6e30: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
6e40: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
6e50: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
6e60: 64 2e 20 20 54 68 69 73 20 77 69 6c 6c 20 61 6c  d.  This will al
6e70: 77 61 79 73 20 62 65 20 73 65 74 20 66 6f 72 20  ways be set for 
6e80: 54 45 4d 50 20 0a 2a 2a 20 64 61 74 61 62 61 73  TEMP .** databas
6e90: 65 73 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 73 20  es and journals 
6ea0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
6eb0: 61 6c 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53  als.  The .** [S
6ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
6ed0: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  SIVE] flag means
6ee0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
6ef0: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f   be opened.** fo
6f00: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
6f10: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69  ss.  This flag i
6f20: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69  s set for all fi
6f30: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f  les except.** fo
6f40: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
6f50: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a 2a 2a  ase file..** .**
6f60: 20 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74   Space to hold t
6f70: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
6f80: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
6f90: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
6fa0: 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f   .** argument to
6fb0: 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f 63 61   xOpen is alloca
6fc0: 74 65 64 20 62 79 20 63 61 6c 6c 65 72 20 28 74  ted by caller (t
6fd0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 29 2e  he SQLite core).
6fe0: 20 0a 2a 2a 20 73 7a 4f 73 46 69 6c 65 20 62 79   .** szOsFile by
6ff0: 74 65 73 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  tes are allocate
7000: 64 20 66 6f 72 20 74 68 69 73 20 6f 62 6a 65 63  d for this objec
7010: 74 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  t.  The xOpen me
7020: 74 68 6f 64 0a 2a 2a 20 66 69 6c 6c 73 20 69 6e  thod.** fills in
7030: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
7040: 70 61 63 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  pace..** .** The
7050: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7060: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
7070: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
7080: 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74  SS_EXISTS] .** t
7090: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
70a0: 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66 69  xistance of a fi
70b0: 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  le,.** or [SQLIT
70c0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
70d0: 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73  TE] to test to s
70e0: 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20  ee.** if a file 
70f0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
7100: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
7110: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
7120: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20  ].** to test to 
7130: 73 65 65 20 69 66 20 61 20 66 69 6c 65 20 69 73  see if a file is
7140: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
7150: 6c 65 2e 20 20 54 68 65 20 66 69 6c 65 20 63 61  le.  The file ca
7160: 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63  n be a .** direc
7170: 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c  tory..** .** SQL
7180: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
7190: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
71a0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
71b0: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f  yte for.** the o
71c0: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f  utput buffers fo
71d0: 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61  r xGetTempname a
71e0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  nd xFullPathname
71f0: 2e 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20 73  . The exact.** s
7200: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
7210: 74 20 62 75 66 66 65 72 20 69 73 20 61 6c 73 6f  t buffer is also
7220: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
7230: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 0a  ameter to both .
7240: 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  ** methods. If t
7250: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
7260: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
7270: 6f 75 67 68 2c 20 53 51 4c 49 54 45 5f 43 41 4e  ough, SQLITE_CAN
7280: 54 4f 50 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20  TOPEN.** should 
7290: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 41 73 20  be returned. As 
72a0: 74 68 69 73 20 69 73 20 68 61 6e 64 6c 65 64 20  this is handled 
72b0: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
72c0: 20 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 76   by SQLite,.** v
72d0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
72e0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 76 6f  ns should endevo
72f0: 75 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ur to prevent th
7300: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 0a 2a  is by setting .*
7310: 2a 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  * mxPathname to 
7320: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
7330: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a  arge value..** .
7340: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
7350: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
7360: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
7370: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
7380: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
7390: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
73a0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
73b0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
73c0: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
73d0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
73e0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
73f0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
7400: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
7410: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
7420: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
7430: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
7440: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
7450: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
7460: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
7470: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
7480: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
7490: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20 54  ess obtained.  T
74a0: 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d  he.** xSleep() m
74b0: 65 74 68 6f 64 20 63 61 75 73 65 20 74 68 65 20  ethod cause the 
74c0: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
74d0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
74e0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
74f0: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
7500: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78  ds given.  The x
7510: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
7520: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7530: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
7540: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
7550: 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20  ent date and.** 
7560: 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  time..*/.typedef
7570: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7580: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
7590: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
75a0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
75b0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
75c0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
75d0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
75e0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
75f0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
7600: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
7610: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
7620: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
7630: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
7640: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
7650: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
7660: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
7670: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
7680: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
7690: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
76a0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
76b0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
76c0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
76d0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
76e0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
76f0: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
7700: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
7710: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
7720: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
7730: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
7740: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
7750: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
7760: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
7770: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
7780: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
7790: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
77a0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
77b0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
77c0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
77d0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
77e0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
77f0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
7800: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  s);.  int (*xGet
7810: 54 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74 65  Tempname)(sqlite
7820: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74  3_vfs*, int nOut
7830: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
7840: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
7850: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
7860: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7870: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
7880: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
7890: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
78a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
78b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
78c0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
78d0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
78e0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
78f0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
7900: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
7910: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
7920: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
7930: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20  har *zSymbol);. 
7940: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
7950: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
7960: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
7970: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
7980: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
7990: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
79a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
79b0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
79c0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
79d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
79e0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
79f0: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
7a00: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
7a10: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
7a20: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
7a30: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
7a40: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
7a50: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
7a60: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
7a70: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
7a80: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
7a90: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
7aa0: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31  s VFS method {F1
7ab0: 31 31 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  1150}.**.** {F11
7ac0: 31 35 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67  151} These integ
7ad0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
7ae0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
7af0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
7b00: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
7b10: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
7b20: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
7b30: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79  ect. {END}  They
7b40: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
7b50: 65 20 6b 69 6e 64 20 6f 66 20 77 68 61 74 20 6b  e kind of what k
7b60: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
7b70: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
7b80: 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b  ethod is.** look
7b90: 69 6e 67 20 66 6f 72 2e 20 20 7b 46 31 31 31 35  ing for.  {F1115
7ba0: 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  2} With SQLITE_A
7bb0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
7bc0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
7bd0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
7be0: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
7bf0: 66 69 6c 65 20 65 78 69 73 74 73 2e 20 7b 46 31  file exists. {F1
7c00: 31 31 35 33 7d 20 57 69 74 68 0a 2a 2a 20 53 51  1153} With.** SQ
7c10: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
7c20: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
7c30: 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  ss method checks
7c40: 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 74 68   to see.** if th
7c50: 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72  e file is both r
7c60: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
7c70: 61 62 6c 65 2e 20 20 7b 46 31 31 31 35 34 7d 20  able.  {F11154} 
7c80: 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41  With.** SQLITE_A
7c90: 43 43 45 53 53 5f 52 45 41 44 20 74 68 65 20 78  CCESS_READ the x
7ca0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
7cb0: 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69   checks to see i
7cc0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  f the file is re
7cd0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
7ce0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
7cf0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
7d00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
7d10: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
7d20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
7d30: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
7d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7d50: 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
7d60: 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
7d70: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32 30  ult Codes {F1220
7d80: 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31  0}.**.** {F12201
7d90: 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  } This routine e
7da0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
7db0: 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  es the.** [SQLIT
7dc0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
7dd0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
7de0: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 2e 20 7b  odes] feature. {
7df0: 46 31 32 32 30 32 7d 0a 2a 2a 20 42 79 20 64 65  F12202}.** By de
7e00: 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50  fault, SQLite AP
7e10: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
7e20: 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36  n one of only 26
7e30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
7e40: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
7e50: 63 6f 64 65 73 5d 2e 20 20 7b 46 31 32 32 30 33  codes].  {F12203
7e60: 7d 20 57 68 65 6e 20 65 78 74 65 6e 64 65 64 20  } When extended 
7e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20  result codes.** 
7e80: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 74  are enabled by t
7e90: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 65  his routine, the
7ea0: 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20 72 65   repetoire of re
7eb0: 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e 20 62  sult codes can b
7ec0: 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67 65 72  e.** much larger
7ed0: 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65 66 75   and can (hopefu
7ee0: 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d 6f 72  lly) provide mor
7ef0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
7f00: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
7f10: 74 68 65 20 63 61 75 73 65 20 6f 66 20 61 6e 20  the cause of an 
7f20: 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  error..**.** {F1
7f30: 32 32 30 34 7d 20 54 68 65 20 73 65 63 6f 6e 64  2204} The second
7f40: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62   argument is a b
7f50: 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61  oolean value tha
7f60: 74 20 74 75 72 6e 73 20 65 78 74 65 6e 64 65 64  t turns extended
7f70: 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
7f80: 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 20 7b 46 31   on and off. {F1
7f90: 32 32 30 35 7d 20 45 78 74 65 6e 64 65 64 20 72  2205} Extended r
7fa0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
7fb0: 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 20 66  off by default f
7fc0: 6f 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  or.** backwards 
7fd0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
7fe0: 74 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e  th older version
7ff0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
8000: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
8010: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
8020: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
8030: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
8040: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
8050: 73 65 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32  sert Rowid {F122
8060: 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32  20}.**.** {F1222
8070: 31 7d 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e  1} Each entry in
8080: 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
8090: 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
80a0: 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
80b0: 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
80c0: 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 20  d the "rowid".  
80d0: 7b 46 31 32 32 32 32 7d 20 54 68 65 20 72 6f 77  {F12222} The row
80e0: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
80f0: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
8100: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
8110: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
8120: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
8130: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
8140: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
8150: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
8160: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
8170: 64 20 63 6f 6c 75 6d 6e 73 2e 20 7b 46 31 32 32  d columns. {F122
8180: 32 33 7d 20 49 66 0a 2a 2a 20 74 68 65 20 74 61  23} If.** the ta
8190: 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
81a0: 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45 52   of type INTEGER
81b0: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65   PRIMARY KEY the
81c0: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
81d0: 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61   is another an a
81e0: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
81f0: 69 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32  id..**.** {F1222
8200: 34 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  4} This routine 
8210: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
8220: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
8230: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
8240: 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74  ul INSERT into t
8250: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
8260: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
8270: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77  nnection.** show
8280: 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  n in the first a
8290: 72 67 75 6d 65 6e 74 2e 20 20 7b 46 31 32 32 32  rgument.  {F1222
82a0: 35 7d 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  5} If no success
82b0: 66 75 6c 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68  ful inserts.** h
82c0: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
82d0: 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61  d on this databa
82e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
82f0: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
8300: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 36 7d 20  .**.** {F12226} 
8310: 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63  If an INSERT occ
8320: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
8330: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  gger, then the r
8340: 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69  owid of the.** i
8350: 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73 20 72  nserted row is r
8360: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
8370: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
8380: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a  as the trigger.*
8390: 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 7b  * is running.  {
83a0: 46 31 32 32 32 37 7d 20 42 75 74 20 6f 6e 63 65  F12227} But once
83b0: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
83c0: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
83d0: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
83e0: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
83f0: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
8400: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
8410: 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  d before the.** 
8420: 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a  trigger fired..*
8430: 2a 0a 2a 2a 20 7b 46 31 32 32 32 38 7d 20 41 6e  *.** {F12228} An
8440: 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61 69   INSERT that fai
8450: 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
8460: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
8470: 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
8480: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 61  cessful insert a
8490: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
84a0: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
84b0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
84c0: 20 72 6f 75 74 69 6e 65 2e 20 20 7b 46 31 32 32   routine.  {F122
84d0: 32 39 7d 20 54 68 75 73 20 49 4e 53 45 52 54 20  29} Thus INSERT 
84e0: 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
84f0: 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
8500: 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
8510: 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
8520: 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
8530: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
8540: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
8550: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
8560: 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
8570: 6e 20 66 61 69 6c 73 2e 20 20 7b 46 31 32 32 33  n fails.  {F1223
8580: 31 7d 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  1} When INSERT O
8590: 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e  R REPLACE .** en
85a0: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
85b0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
85c0: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
85d0: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
85e0: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
85f0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
8600: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
8610: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
8620: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
8630: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
8640: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
8650: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
8660: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
8670: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
8680: 65 2e 20 0a 2a 2a 0a 2a 2a 20 7b 55 46 31 32 32  e. .**.** {UF122
8690: 33 32 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74  32} If another t
86a0: 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77  hread does a new
86b0: 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73   insert on the s
86c0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
86d0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
86e0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
86f0: 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
8700: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
8710: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c  st insert rowid,
8720: 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
8730: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
8740: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
8750: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74  efined..*/.sqlit
8760: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
8770: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
8780: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
8790: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
87a0: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
87b0: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
87c0: 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F12240}.**.** 
87d0: 7b 46 31 32 32 34 31 7d 20 54 68 69 73 20 66 75  {F12241} This fu
87e0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
87f0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
8800: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
8810: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
8820: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
8830: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
8840: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
8850: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
8860: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f  ent.** on the co
8870: 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
8880: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
8890: 70 61 72 61 6d 65 74 65 72 2e 20 7b 46 31 32 32  parameter. {F122
88a0: 34 32 7d 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e  42} Only.** chan
88b0: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
88c0: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
88d0: 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
88e0: 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c  PDATE, or.** DEL
88f0: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
8900: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
8910: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
8920: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
8930: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ers are not coun
8940: 74 65 64 2e 20 7b 46 31 32 32 34 33 7d 20 55 73  ted. {F12243} Us
8950: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
8960: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
8970: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  function.** to f
8980: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
8990: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
89a0: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
89b0: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
89c0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  gers..**.** {F12
89d0: 32 34 34 7d 20 57 69 74 68 69 6e 20 74 68 65 20  244} Within the 
89e0: 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
89f0: 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  r, the sqlite3_c
8a00: 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
8a10: 63 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c  ce can be.** cal
8a20: 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
8a30: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
8a40: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
8a50: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
8a60: 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
8a70: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
8a80: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
8a90: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
8aa0: 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
8ab0: 20 7b 46 31 32 32 34 35 7d 20 41 6c 6c 20 63 68   {F12245} All ch
8ac0: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
8ad0: 64 2c 20 65 76 65 6e 20 69 66 20 74 68 65 79 20  d, even if they 
8ae0: 77 65 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e  were later undon
8af0: 65 20 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41  e by a.** ROLLBA
8b00: 43 4b 20 6f 72 20 41 42 4f 52 54 2e 20 20 7b 46  CK or ABORT.  {F
8b10: 31 32 32 34 36 7d 20 45 78 63 65 70 74 2c 20 63  12246} Except, c
8b20: 68 61 6e 67 65 73 20 61 73 73 6f 63 69 61 74 65  hanges associate
8b30: 64 20 77 69 74 68 20 63 72 65 61 74 69 6e 67 20  d with creating 
8b40: 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 20  and.** dropping 
8b50: 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 63  tables are not c
8b60: 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ounted..**.** {F
8b70: 31 32 32 34 37 7d 20 49 66 20 61 20 63 61 6c 6c  12247} If a call
8b80: 62 61 63 6b 20 69 6e 76 6f 6b 65 73 20 5b 73 71  back invokes [sq
8b90: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
8ba0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
8bb0: 5d 0a 2a 2a 20 72 65 63 75 72 73 69 76 65 6c 79  ].** recursively
8bc0: 2c 20 74 68 65 6e 20 74 68 65 20 63 68 61 6e 67  , then the chang
8bd0: 65 73 20 69 6e 20 74 68 65 20 69 6e 6e 65 72 2c  es in the inner,
8be0: 20 72 65 63 75 72 73 69 76 65 20 63 61 6c 6c 20   recursive call 
8bf0: 61 72 65 0a 2a 2a 20 63 6f 75 6e 74 65 64 20 74  are.** counted t
8c00: 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
8c10: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
8c20: 6f 75 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  outer call..**.*
8c30: 2a 20 7b 46 31 32 32 34 38 7d 20 53 51 4c 69 74  * {F12248} SQLit
8c40: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
8c50: 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
8c60: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
8c70: 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20  hout.** a WHERE 
8c80: 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69  clause by droppi
8c90: 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
8ca0: 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
8cb0: 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66  his is much.** f
8cc0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
8cd0: 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
8ce0: 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
8cf0: 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
8d00: 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42  he.** table.)  B
8d10: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f  ecause of this o
8d20: 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
8d30: 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f   change count fo
8d40: 72 20 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  r .** "DELETE FR
8d50: 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62  OM table" will b
8d60: 65 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73  e zero regardles
8d70: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
8d80: 6f 66 20 65 6c 65 6d 65 6e 74 73 0a 2a 2a 20 74  of elements.** t
8d90: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
8da0: 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  lly in the table
8db0: 2e 20 7b 46 31 32 32 35 31 7d 20 54 6f 20 67 65  . {F12251} To ge
8dc0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
8dd0: 75 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 75  unt.** of the nu
8de0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c  mber of rows del
8df0: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45  eted, use.** "DE
8e00: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20  LETE FROM table 
8e10: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64  WHERE 1" instead
8e20: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 46 31 32 32 35 32  ..**.** {UF12252
8e30: 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  } If another thr
8e40: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
8e50: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
8e60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8e70: 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20  n.** while this 
8e80: 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
8e90: 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ng then the retu
8ea0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
8eb0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75   routine.** is u
8ec0: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
8ed0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
8ee0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
8ef0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
8f00: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
8f10: 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32  s Modified {F122
8f20: 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  60}.***.** {F122
8f30: 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f  61} This functio
8f40: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
8f50: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
8f60: 20 72 6f 77 73 20 74 68 61 74 20 68 61 76 65 20   rows that have 
8f70: 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64  been.** modified
8f80: 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41   by INSERT, UPDA
8f90: 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
8fa0: 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
8fb0: 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
8fc0: 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e  e.** was opened.
8fd0: 20 7b 46 31 32 32 36 32 7d 20 54 68 65 20 63 6f   {F12262} The co
8fe0: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 55 50 44  unt includes UPD
8ff0: 41 54 45 2c 20 49 4e 53 45 52 54 20 61 6e 64 20  ATE, INSERT and 
9000: 44 45 4c 45 54 45 20 0a 2a 2a 20 73 74 61 74 65  DELETE .** state
9010: 6d 65 6e 74 73 20 65 78 65 63 75 74 65 64 20 61  ments executed a
9020: 73 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  s part of trigge
9030: 72 20 70 72 6f 67 72 61 6d 73 2e 20 20 7b 46 31  r programs.  {F1
9040: 32 32 36 33 7d 20 41 6c 6c 20 63 68 61 6e 67 65  2263} All change
9050: 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64  s.** are counted
9060: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
9070: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
9080: 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
9090: 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77 68 65 6e  pleted .** (when
90a0: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
90b0: 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20  andle is passed 
90c0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
90d0: 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71 6c  t()] or .** [sql
90e0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
90f0: 29 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53  ). {END}.**.** S
9100: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
9110: 69 74 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 69  ite3_change()] i
9120: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
9130: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
9140: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
9150: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
9160: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
9170: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
9180: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
9190: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
91a0: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
91b0: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
91c0: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
91d0: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
91e0: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
91f0: 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  orm the table.) 
9200: 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74   Because of.** t
9210: 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
9220: 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75  , the change cou
9230: 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46  nt for "DELETE F
9240: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20  ROM table" will 
9250: 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72  be.** zero regar
9260: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
9270: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
9280: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
9290: 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74  ally in the.** t
92a0: 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20  able. To get an 
92b0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
92c0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
92d0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
92e0: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
92f0: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
9300: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
9310: 7b 55 31 32 32 36 34 7d 20 49 66 20 61 6e 6f 74  {U12264} If anot
9320: 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65 73  her thread makes
9330: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
9340: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
9350: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
9360: 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
9370: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
9380: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
9390: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  of this routine.
93a0: 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
93b0: 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71   {END}.*/.int sq
93c0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
93d0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
93e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
93f0: 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
9400: 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
9410: 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12270}.**.** {F
9420: 31 32 32 37 31 7d 20 54 68 69 73 20 66 75 6e 63  12271} This func
9430: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
9440: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
9450: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
9460: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
9470: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
9480: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 7b  t opportunity. {
9490: 45 4e 44 7d 20 54 68 69 73 20 72 6f 75 74 69 6e  END} This routin
94a0: 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
94b0: 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
94c0: 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
94d0: 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
94e0: 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
94f0: 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
9500: 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
9510: 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
9520: 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
9530: 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
9540: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20  .**.** {F12272} 
9550: 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
9560: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
9570: 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
9580: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
9590: 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
95a0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
95b0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
95c0: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 7b 55 31  e operation. {U1
95d0: 32 32 37 33 7d 20 42 75 74 20 69 74 0a 2a 2a 20  2273} But it.** 
95e0: 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
95f0: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
9600: 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
9610: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
9620: 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
9630: 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
9640: 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
9650: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
9660: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 34 7d 20  .**.** {F12274} 
9670: 54 68 65 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  The SQL operatio
9680: 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
9690: 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
96a0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  n.** [SQLITE_INT
96b0: 45 52 52 55 50 54 5d 2e 20 20 7b 46 31 32 32 37  ERRUPT].  {F1227
96c0: 35 7d 20 49 66 20 61 6e 20 69 6e 74 65 72 72 75  5} If an interru
96d0: 70 74 65 64 20 6f 70 65 72 61 74 69 6f 6e 20 77  pted operation w
96e0: 61 73 20 61 6e 0a 2a 2a 20 75 70 64 61 74 65 20  as an.** update 
96f0: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
9700: 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
9710: 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
9720: 20 65 6e 74 69 72 65 0a 2a 2a 20 74 72 61 6e 73   entire.** trans
9730: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72  action will be r
9740: 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
9750: 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69  atically..*/.voi
9760: 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
9770: 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
9780: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9790: 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
97a0: 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
97b0: 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35 31   Complete {F1051
97c0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
97d0: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
97e0: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
97f0: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
9800: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
9810: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
9820: 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e  ed text forms on
9830: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65  e or more comple
9840: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
9850: 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  s or.** if addit
9860: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
9870: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
9880: 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65  ding the stateme
9890: 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  nts into.** SQLi
98a0: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
98b0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
98c0: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
98d0: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
98e0: 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
98f0: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
9900: 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74  statement.  A st
9910: 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
9920: 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
9930: 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
9940: 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
9950: 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61  and is not a fra
9960: 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52  gment of a.** CR
9970: 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
9980: 74 65 6d 65 6e 74 2e 20 20 54 68 65 73 65 20 72  tement.  These r
9990: 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
99a0: 61 72 73 65 20 74 68 65 20 53 51 4c 20 61 6e 64  arse the SQL and
99b0: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
99c0: 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
99d0: 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
99e0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20  .**.** {F10511} 
99f0: 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
9a00: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
9a10: 68 65 20 67 69 76 65 6e 20 69 6e 70 75 74 20 73  he given input s
9a20: 74 72 69 6e 67 20 0a 2a 2a 20 65 6e 64 73 20 77  tring .** ends w
9a30: 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
9a40: 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f  optionally follo
9a50: 77 65 64 20 62 79 20 77 68 69 74 65 73 70 61 63  wed by whitespac
9a60: 65 20 6f 72 0a 2a 2a 20 63 6f 6d 6d 65 6e 74 73  e or.** comments
9a70: 2e 20 7b 46 31 30 35 31 32 7d 20 46 6f 72 20 73  . {F10512} For s
9a80: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
9a90: 29 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65  ),.** the parame
9aa0: 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ter must be a ze
9ab0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
9ac0: 46 2d 38 20 73 74 72 69 6e 67 2e 20 7b 46 31 30  F-8 string. {F10
9ad0: 35 31 33 7d 20 46 6f 72 0a 2a 2a 20 73 71 6c 69  513} For.** sqli
9ae0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
9af0: 2c 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  , a zero-termina
9b00: 74 65 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65  ted machine byte
9b10: 20 6f 72 64 65 72 20 55 54 46 2d 31 36 20 73 74   order UTF-16 st
9b20: 72 69 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69  ring.** is requi
9b30: 72 65 64 2e 20 20 7b 46 31 30 35 31 34 7d 20 54  red.  {F10514} T
9b40: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
9b50: 74 75 72 6e 20 66 61 6c 73 65 20 69 66 20 74 68  turn false if th
9b60: 65 20 74 65 72 6d 69 6e 61 6c 0a 2a 2a 20 73 65  e terminal.** se
9b70: 6d 69 63 6f 6c 6f 6e 20 69 73 20 77 69 74 68 69  micolon is withi
9b80: 6e 20 61 20 63 6f 6d 6d 65 6e 74 2c 20 61 20 73  n a comment, a s
9b90: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 6f 72  tring literal or
9ba0: 20 61 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69   a quoted identi
9bb0: 66 69 65 72 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  fier.** (in othe
9bc0: 72 20 77 6f 72 64 73 20 69 66 20 74 68 65 20 66  r words if the f
9bd0: 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 69  inal semicolon i
9be0: 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 61 20 73  s not really a s
9bf0: 65 70 61 72 61 74 65 20 74 6f 6b 65 6e 0a 2a 2a  eparate token.**
9c00: 20 62 75 74 20 70 61 72 74 20 6f 66 20 61 20 6c   but part of a l
9c10: 61 72 67 65 72 20 74 6f 6b 65 6e 29 20 6f 72 20  arger token) or 
9c20: 69 66 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  if the final sem
9c30: 69 63 6f 6c 6f 6e 20 69 73 0a 2a 2a 20 69 6e 20  icolon is.** in 
9c40: 62 65 74 77 65 65 6e 20 74 68 65 20 42 45 47 49  between the BEGI
9c50: 4e 20 61 6e 64 20 45 4e 44 20 6b 65 79 77 6f 72  N and END keywor
9c60: 64 73 20 6f 66 20 61 20 43 52 45 41 54 45 20 54  ds of a CREATE T
9c70: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
9c80: 2e 0a 2a 2a 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e  ..** {END}.*/.in
9c90: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
9ca0: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
9cb0: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
9cc0: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
9cd0: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
9ce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
9cf0: 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
9d00: 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
9d10: 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20  ITE_BUSY Errors 
9d20: 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12310}.**.** {
9d30: 46 31 32 33 31 31 7d 20 54 68 69 73 20 72 6f 75  F12311} This rou
9d40: 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73 20  tine identifies 
9d50: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
9d60: 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
9d70: 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  e.** invoked whe
9d80: 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70 74  never an attempt
9d90: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
9da0: 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
9db0: 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68  e .** that anoth
9dc0: 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72 6f  er thread or pro
9dd0: 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
9de0: 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 49 66 20  .** {F12312} If 
9df0: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
9e00: 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
9e10: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
9e20: 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65 73 20 5b   (or sometimes [
9e30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9e40: 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20 72 65 74  CKED]).** is ret
9e50: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
9e60: 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
9e70: 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ing the lock..**
9e80: 20 7b 46 31 32 33 31 33 7d 20 49 66 20 74 68 65   {F12313} If the
9e90: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
9ea0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
9eb0: 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b   the.** callback
9ec0: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
9ed0: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
9ee0: 6e 74 73 2e 20 20 7b 46 31 32 33 31 34 7d 20 54  nts.  {F12314} T
9ef0: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
9f00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
9f10: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
9f20: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
9f30: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
9f40: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
9f50: 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  t to this routin
9f60: 65 2e 20 20 7b 46 31 32 33 31 35 7d 20 54 68 65  e.  {F12315} The
9f70: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
9f80: 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
9f90: 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
9fa0: 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
9fb0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
9fc0: 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
9fd0: 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
9fe0: 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 7b 46 31  king event.  {F1
9ff0: 32 33 31 36 7d 20 49 66 20 74 68 65 0a 2a 2a 20  2316} If the.** 
a000: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
a010: 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
a020: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
a030: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
a040: 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
a050: 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
a060: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
a070: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
a080: 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
a090: 0a 2a 2a 20 7b 46 31 32 33 31 37 7d 20 49 66 20  .** {F12317} If 
a0a0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
a0b0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
a0c0: 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
a0d0: 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
a0e0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
a0f0: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
a100: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
a110: 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  peats..**.** {U1
a120: 32 33 31 38 7d 20 54 68 65 20 70 72 65 73 65 6e  2318} The presen
a130: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
a140: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
a150: 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20  arantee that.** 
a160: 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
a170: 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ed when there is
a180: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
a190: 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64  ..** If SQLite d
a1a0: 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
a1b0: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
a1c0: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
a1d0: 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65  esult in.** a de
a1e0: 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
a1f0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
a200: 55 53 59 5d 20 69 6e 73 74 65 61 64 2e 20 7b 45  USY] instead. {E
a210: 4e 44 7d 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  ND}.** Consider 
a220: 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
a230: 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
a240: 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
a250: 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
a260: 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
a270: 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
a280: 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
a290: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
a2a0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
a2b0: 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
a2c0: 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
a2d0: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
a2e0: 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
a2f0: 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
a300: 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
a310: 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
a320: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
a330: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
a340: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
a350: 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
a360: 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
a370: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
a380: 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
a390: 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
a3a0: 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
a3b0: 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
a3c0: 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
a3d0: 72 65 73 73 2e 20 20 0a 2a 2a 20 7b 46 31 32 33  ress.  .** {F123
a3e0: 31 39 7d 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  19} Therefore,.*
a3f0: 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
a400: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
a410: 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
a420: 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
a430: 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
a440: 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
a450: 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
a460: 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
a470: 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
a480: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
a490: 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
a4a0: 2a 2a 20 7b 46 31 32 33 32 31 7d 20 54 68 65 20  ** {F12321} The 
a4b0: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
a4c0: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
a4d0: 2a 0a 2a 2a 20 7b 46 31 32 33 32 32 7d 20 54 68  *.** {F12322} Th
a4e0: 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
a4f0: 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
a500: 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
a510: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
a520: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
a530: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
a540: 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
a550: 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
a560: 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
a570: 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
a580: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
a590: 68 65 2e 20 20 7b 46 31 32 33 32 33 7d 20 53 51  he.  {F12323} SQ
a5a0: 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
a5b0: 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
a5c0: 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
a5d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a5e0: 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
a5f0: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
a600: 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
a610: 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
a620: 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
a630: 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
a640: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
a650: 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
a660: 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
a670: 72 73 2e 20 20 7b 46 31 32 33 32 34 7d 20 49 66  rs.  {F12324} If
a680: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
a690: 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
a6a0: 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
a6b0: 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
a6c0: 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
a6d0: 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
a6e0: 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
a6f0: 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
a700: 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
a710: 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
a720: 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
a730: 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
a740: 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
a750: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
a760: 20 20 7b 46 31 32 33 32 35 7d 20 54 68 69 73 20    {F12325} This 
a770: 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
a780: 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
a790: 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
a7a0: 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
a7b0: 67 65 73 2e 20 7b 45 4e 44 7d 20 53 65 65 20 74  ges. {END} See t
a7c0: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
a7d0: 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65  ttp://www.sqlite
a7e0: 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b  .org/cvstrac/wik
a7f0: 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
a800: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
a810: 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
a820: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
a830: 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
a840: 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
a850: 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
a860: 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
a870: 2a 09 0a 2a 2a 20 7b 46 31 32 33 32 36 7d 20 53  *..** {F12326} S
a880: 71 6c 69 74 65 20 69 73 20 72 65 2d 65 6e 74 72  qlite is re-entr
a890: 61 6e 74 2c 20 73 6f 20 74 68 65 20 62 75 73 79  ant, so the busy
a8a0: 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 73 74 61   handler may sta
a8b0: 72 74 20 61 20 6e 65 77 0a 2a 2a 20 71 75 65 72  rt a new.** quer
a8c0: 79 2e 20 7b 45 4e 44 7d 20 28 49 74 20 69 73 20  y. {END} (It is 
a8d0: 6e 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61 6e  not clear why an
a8e0: 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72 79  yone would every
a8f0: 20 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69 73   want to do this
a900: 2c 0a 2a 2a 20 62 75 74 20 69 74 20 69 73 20 61  ,.** but it is a
a910: 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f 72  llowed, in theor
a920: 79 2e 29 20 7b 55 31 32 33 32 37 7d 20 42 75 74  y.) {U12327} But
a930: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
a940: 72 20 6d 61 79 20 6e 6f 74 0a 2a 2a 20 63 6c 6f  r may not.** clo
a950: 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  se the database.
a960: 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61    Closing the da
a970: 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75  tabase from a bu
a980: 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  sy handler will 
a990: 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20  delete .** data 
a9a0: 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66  structures out f
a9b0: 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78  rom under the ex
a9c0: 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e  ecuting query an
a9d0: 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61  d will .** proba
a9e0: 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20  bly result in a 
a9f0: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
aa00: 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74  lt or other runt
aa10: 69 6d 65 20 65 72 72 6f 72 2e 20 7b 45 4e 44 7d  ime error. {END}
aa20: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 32 38 7d 20  .**.** {F12328} 
aa30: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
aa40: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
aa50: 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
aa60: 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
aa70: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
aa80: 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
aa90: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
aaa0: 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ars any previous
aab0: 20 6f 6e 65 2e 20 0a 2a 2a 20 7b 46 31 32 33 32   one. .** {F1232
aac0: 39 7d 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  9} Note that cal
aad0: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
aae0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69  sy_timeout()] wi
aaf0: 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
ab00: 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79  lear.** the busy
ab10: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
ab20: 7b 46 31 32 33 33 31 7d 20 57 68 65 6e 20 6f 70  {F12331} When op
ab30: 65 72 61 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69  erating in [sqli
ab40: 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
ab50: 64 5f 63 61 63 68 65 20 7c 20 73 68 61 72 65 64  d_cache | shared
ab60: 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a   cache mode],.**
ab70: 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 62   only a single b
ab80: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6e 20  usy handler can 
ab90: 62 65 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  be defined for e
aba0: 61 63 68 20 64 61 74 61 62 61 73 65 20 66 69 6c  ach database fil
abb0: 65 2e 0a 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20  e..** So if two 
abc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
abd0: 69 6f 6e 73 20 73 68 61 72 65 20 61 20 73 69 6e  ions share a sin
abe0: 67 6c 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20  gle cache, then 
abf0: 63 68 61 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20  changing.** the 
ac00: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20  busy handler on 
ac10: 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  one connection w
ac20: 69 6c 6c 20 61 6c 73 6f 20 63 68 61 6e 67 65 20  ill also change 
ac30: 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
ac40: 6c 65 72 20 69 6e 20 74 68 65 20 6f 74 68 65 72  ler in the other
ac50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 7b 46   connection.  {F
ac60: 31 32 33 33 32 7d 20 54 68 65 20 62 75 73 79 20  12332} The busy 
ac70: 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b  handler is invok
ac80: 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 74 68 72  ed.** in the thr
ac90: 65 61 64 20 74 68 61 74 20 77 61 73 20 72 75 6e  ead that was run
aca0: 6e 69 6e 67 20 77 68 65 6e 20 74 68 65 20 53 51  ning when the SQ
acb0: 4c 49 54 45 5f 42 55 53 59 20 77 61 73 20 68 69  LITE_BUSY was hi
acc0: 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
acd0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
ace0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
acf0: 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
ad00: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
ad10: 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
ad20: 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d  Timeout {F12340}
ad30: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20  .**.** {F12341} 
ad40: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
ad50: 73 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  s a busy handler
ad60: 20 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72   that sleeps for
ad70: 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a   a while when a.
ad80: 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b  ** table is lock
ad90: 65 64 2e 20 20 7b 46 31 32 33 34 32 7d 20 54 68  ed.  {F12342} Th
ada0: 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73  e handler will s
adb0: 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
adc0: 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74  mes until .** at
add0: 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
ade0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
adf0: 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64  ping have been d
ae00: 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20 41 66  one. {F12343} Af
ae10: 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c  ter.** "ms" mill
ae20: 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
ae30: 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c 65  ping, the handle
ae40: 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
ae50: 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71 6c  h.** causes [sql
ae60: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
ae70: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
ae80: 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
ae90: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
aea0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20 43  **.** {F12344} C
aeb0: 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
aec0: 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
aed0: 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
aee0: 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
aef0: 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
af00: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
af10: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 35 7d 20 54  **.** {F12345} T
af20: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
af30: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
af40: 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
af50: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
af60: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
af70: 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
af80: 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66   handler was def
af90: 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67  ined  .** (using
afa0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
afb0: 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
afc0: 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
afd0: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
afe0: 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
aff0: 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
b000: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
b010: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
b020: 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
b030: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b040: 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
b050: 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
b060: 67 20 51 75 65 72 69 65 73 20 7b 46 31 32 33 37  g Queries {F1237
b070: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65  0}.**.** This ne
b080: 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  xt routine is a 
b090: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
b0a0: 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69  per around [sqli
b0b0: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20  te3_exec()]..** 
b0c0: 7b 46 31 32 33 37 31 7d 20 49 6e 73 74 65 61 64  {F12371} Instead
b0d0: 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75   of invoking a u
b0e0: 73 65 72 2d 73 75 70 70 6c 69 65 64 20 63 61 6c  ser-supplied cal
b0f0: 6c 62 61 63 6b 20 66 6f 72 20 65 61 63 68 20 72  lback for each r
b100: 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73  ow of the.** res
b110: 75 6c 74 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ult, this routin
b120: 65 20 72 65 6d 65 6d 62 65 72 73 20 65 61 63 68  e remembers each
b130: 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
b140: 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  lt in memory.** 
b150: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b160: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
b170: 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61  , then returns a
b180: 6c 6c 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ll of the result
b190: 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 71 75   after the.** qu
b1a0: 65 72 79 20 68 61 73 20 66 69 6e 69 73 68 65 64  ery has finished
b1b0: 2e 20 7b 46 31 32 33 37 32 7d 0a 2a 2a 0a 2a 2a  . {F12372}.**.**
b1c0: 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20   As an example, 
b1d0: 73 75 70 70 6f 73 65 20 74 68 65 20 71 75 65 72  suppose the quer
b1e0: 79 20 72 65 73 75 6c 74 20 77 68 65 72 65 20 74  y result where t
b1f0: 68 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a  his table:.**.**
b200: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
b210: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
b220: 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
b230: 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
b240: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
b250: 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
b260: 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
b270: 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
b280: 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
b290: 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
b2a0: 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
b2b0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49  ckquote>.**.** I
b2c0: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
b2d0: 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73 75 6c  nt were &azResul
b2e0: 74 20 74 68 65 6e 20 61 66 74 65 72 20 74 68 65  t then after the
b2f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
b300: 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20 77 69  s.** azResult wi
b310: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 66  ll contain the f
b320: 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a 2a  ollowing data:.*
b330: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
b340: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
b350: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
b360: 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
b370: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
b380: 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
b390: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
b3a0: 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
b3b0: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
b3c0: 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
b3d0: 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
b3e0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
b3f0: 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
b400: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
b410: 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
b420: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
b430: 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
b440: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
b450: 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
b460: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
b470: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f  kquote>.**.** No
b480: 74 69 63 65 20 74 68 61 74 20 74 68 65 72 65 20  tice that there 
b490: 69 73 20 61 6e 20 65 78 74 72 61 20 72 6f 77 20  is an extra row 
b4a0: 6f 66 20 64 61 74 61 20 63 6f 6e 74 61 69 6e 69  of data containi
b4b0: 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a  ng the column.**
b4c0: 20 68 65 61 64 65 72 73 2e 20 20 42 75 74 20 74   headers.  But t
b4d0: 68 65 20 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20  he *nrow return 
b4e0: 76 61 6c 75 65 20 69 73 20 73 74 69 6c 6c 20 33  value is still 3
b4f0: 2e 20 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a  .  *ncolumn is.*
b500: 2a 20 73 65 74 20 74 6f 20 32 2e 20 20 49 6e 20  * set to 2.  In 
b510: 67 65 6e 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d  general, the num
b520: 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e  ber of values in
b530: 73 65 72 74 65 64 20 69 6e 74 6f 20 61 7a 52 65  serted into azRe
b540: 73 75 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  sult.** will be 
b550: 28 28 2a 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a  ((*nrow) + 1)*(*
b560: 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20  ncolumn)..**.** 
b570: 7b 55 31 32 33 37 34 7d 20 41 66 74 65 72 20 74  {U12374} After t
b580: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
b590: 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
b5a0: 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
b5b0: 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  t, it should .**
b5c0: 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
b5d0: 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f   data pointer to
b5e0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
b5f0: 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
b600: 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  o .** release th
b610: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
b620: 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65  s malloc-ed.  Be
b630: 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
b640: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
b650: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
b660: 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  ens, the calling
b670: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
b680: 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a  ot try to call .
b690: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
b6a0: 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
b6b0: 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  nly [sqlite3_fre
b6c0: 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
b6d0: 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a  le to release .*
b6e0: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  * the memory pro
b6f0: 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
b700: 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
b710: 31 32 33 37 33 7d 20 54 68 65 20 72 65 74 75 72  12373} The retur
b720: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
b730: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 73  routine is the s
b740: 61 6d 65 20 61 73 0a 2a 2a 20 66 72 6f 6d 20 5b  ame as.** from [
b750: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
b760: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
b770: 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
b780: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
b790: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
b7a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
b7b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
b7c0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
b7d0: 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20 20 63   executed */.  c
b7e0: 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70 2c 20  har ***resultp, 
b7f0: 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 20        /* Result 
b800: 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63 68 61  written to a cha
b810: 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68 69 73  r *[]  that this
b820: 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a 20 20   points to */.  
b830: 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20  int *nrow,      
b840: 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
b850: 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
b860: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
b870: 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20    int *ncolumn, 
b880: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
b890: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
b8a0: 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
b8b0: 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  e */.  char **er
b8c0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 2f 2a  rmsg          /*
b8d0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
b8e0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
b8f0: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
b900: 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
b910: 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
b920: 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
b930: 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
b940: 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37 34   Functions {F174
b950: 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
b960: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
b970: 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
b980: 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
b990: 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
b9a0: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
b9b0: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
b9c0: 0a 2a 2a 20 7b 46 31 37 34 30 31 7d 20 54 68 65  .** {F17401} The
b9d0: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
b9e0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
b9f0: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
ba00: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
ba10: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
ba20: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
ba30: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
ba40: 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 55 31 37 34  loc()]..** {U174
ba50: 30 32 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  02} The strings 
ba60: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
ba70: 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
ba80: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
ba90: 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
baa0: 5f 66 72 65 65 28 29 5d 2e 20 7b 46 31 37 34 30  _free()]. {F1740
bab0: 33 7d 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65  3}  Both routine
bac0: 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
bad0: 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
bae0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
baf0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
bb00: 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
bb10: 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
bb20: 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
bb30: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ring..**.** {F17
bb40: 34 30 34 7d 20 49 6e 20 73 71 6c 69 74 65 33 5f  404} In sqlite3_
bb50: 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
bb60: 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
bb70: 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
bb80: 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
bb90: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
bba0: 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
bbb0: 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
bbc0: 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
bbd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
bbe0: 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
bbf0: 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
bc00: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
bc10: 61 6d 65 74 65 72 2e 20 7b 45 4e 44 7d 20 4e 6f  ameter. {END} No
bc20: 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
bc30: 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
bc40: 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
bc50: 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
bc60: 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
bc70: 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
bc80: 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
bc90: 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
bca0: 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
bcb0: 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
bcc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
bcd0: 79 2e 20 20 7b 46 31 37 34 30 35 7d 20 4e 6f 74  y.  {F17405} Not
bce0: 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
bcf0: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
bd00: 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
bd10: 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
bd20: 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
bd30: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
bd40: 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
bd50: 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
bd60: 68 65 20 62 75 66 66 65 72 2e 20 7b 45 4e 44 7d  he buffer. {END}
bd70: 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
bd80: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
bd90: 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
bda0: 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
bdb0: 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
bdc0: 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
bdd0: 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
bde0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
bdf0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
be00: 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
be10: 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
be20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
be30: 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20 41 73  *.** {F17406} As
be40: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
be50: 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
be60: 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
be70: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
be80: 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
be90: 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
bea0: 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
beb0: 65 72 6d 69 6e 61 74 65 64 2e 20 7b 46 31 37 34  erminated. {F174
bec0: 30 37 7d 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  07} The first.**
bed0: 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
bee0: 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
bef0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
bf00: 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
bf10: 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
bf20: 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 7b 45 4e  terminator.  {EN
bf30: 44 7d 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  D} So the longes
bf40: 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
bf50: 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
bf60: 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
bf70: 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
bf80: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
bf90: 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
bfa0: 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
bfb0: 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
bfc0: 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
bfd0: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
bfe0: 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
bff0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
c000: 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
c010: 20 70 72 69 6e 74 66 20 66 6f 72 6d 61 74 74 69   printf formatti
c020: 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
c030: 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
c040: 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
c050: 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
c060: 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
c070: 0a 2a 2a 20 7b 46 31 37 34 31 30 7d 20 54 68 65  .** {F17410} The
c080: 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
c090: 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
c0a0: 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
c0b0: 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
c0c0: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
c0d0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
c0e0: 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
c0f0: 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
c100: 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
c110: 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
c120: 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
c130: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
c140: 2e 20 7b 45 4e 44 7d 20 42 79 20 64 6f 75 62 6c  . {END} By doubl
c150: 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
c160: 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
c170: 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
c180: 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
c190: 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
c1a0: 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
c1b0: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
c1c0: 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65  example, so some
c1d0: 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
c1e0: 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
c1f0: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
c200: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
c210: 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
c220: 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
c230: 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
c240: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
c250: 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
c260: 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
c270: 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
c280: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
c290: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
c2a0: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
c2b0: 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
c2c0: 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
c2d0: 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
c2e0: 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
c2f0: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
c300: 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
c310: 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
c320: 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
c330: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
c340: 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
c350: 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
c360: 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
c370: 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
c380: 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
c390: 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
c3a0: 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
c3b0: 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
c3c0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
c3d0: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
c3e0: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
c3f0: 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
c400: 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
c410: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
c420: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
c430: 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
c440: 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
c450: 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
c460: 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
c470: 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
c480: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
c490: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
c4a0: 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
c4b0: 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
c4c0: 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
c4d0: 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
c4e0: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
c4f0: 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
c500: 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
c510: 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
c520: 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
c530: 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20  e you.** should 
c540: 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
c550: 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
c560: 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
c570: 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a  into a string .*
c580: 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  * literal..**.**
c590: 20 7b 46 31 37 34 31 31 7d 20 54 68 65 20 25 51   {F17411} The %Q
c5a0: 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
c5b0: 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
c5c0: 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
c5d0: 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
c5e0: 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
c5f0: 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
c600: 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20 70 61  g.  Or if the pa
c610: 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 61  rameter in the a
c620: 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20  rgument.** list 
c630: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
c640: 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
c650: 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
c660: 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e 67 6c  " (without singl
c670: 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e 20  e.** quotes) in 
c680: 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20  place of the %Q 
c690: 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20 53  option. {END}  S
c6a0: 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
c6b0: 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
c6c0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
c6d0: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
c6e0: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
c6f0: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
c700: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
c710: 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
c720: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
c730: 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
c740: 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
c750: 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
c760: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
c770: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
c780: 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
c790: 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
c7a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
c7b0: 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
c7c0: 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
c7d0: 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
c7e0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
c7f0: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 31 32  r..**.** {F17412
c800: 7d 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  } The "%z" forma
c810: 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
c820: 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20  ks exactly like 
c830: 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a  "%s" with the.**
c840: 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
c850: 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
c860: 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
c870: 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
c880: 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
c890: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
c8a0: 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
c8b0: 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e  nput string. {EN
c8c0: 44 7d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  D}.*/.char *sqli
c8d0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
c8e0: 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
c8f0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
c900: 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
c910: 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
c920: 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
c930: 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
c940: 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
c950: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c960: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
c970: 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46 31  on Subsystem {F1
c980: 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  7300}.**.** {F17
c990: 33 30 31 7d 20 54 68 65 20 53 51 4c 69 74 65 20  301} The SQLite 
c9a0: 63 6f 72 65 20 28 6e 6f 74 20 63 6f 75 6e 74 69  core (not counti
c9b0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  ng operating-sys
c9c0: 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
c9d0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c9e0: 6f 6e 73 29 20 75 73 65 73 20 74 68 65 73 65 20  ons) uses these 
c9f0: 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
ca00: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
ca10: 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
ca20: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ca30: 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  needs. {END}.**.
ca40: 2a 2a 20 7b 46 31 37 33 30 32 7d 20 54 68 65 20  ** {F17302} The 
ca50: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
ca60: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ca70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
ca80: 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
ca90: 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
caa0: 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
cab0: 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
cac0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 7b 46 31 37  rameter..** {F17
cad0: 33 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  303} If sqlite3_
cae0: 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
caf0: 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
cb00: 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
cb10: 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
cb20: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
cb30: 72 2e 20 20 7b 46 31 37 33 30 34 7d 20 49 66 20  r.  {F17304} If 
cb40: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
cb50: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
cb60: 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
cb70: 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
cb80: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cb90: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
cba0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
cbb0: 2a 20 7b 46 31 37 33 30 35 7d 20 43 61 6c 6c 69  * {F17305} Calli
cbc0: 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
cbd0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
cbe0: 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
cbf0: 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
cc00: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
cc10: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
cc20: 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
cc30: 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
cc40: 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
cc50: 73 65 64 2e 20 20 7b 46 31 37 33 30 36 7d 20 54  sed.  {F17306} T
cc60: 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
cc70: 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
cc80: 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
cc90: 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
cca0: 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
ccb0: 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
ccc0: 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
ccd0: 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
cce0: 73 73 2e 20 20 7b 55 31 37 33 30 37 7d 20 41 66  ss.  {U17307} Af
ccf0: 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
cd00: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
cd10: 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
cd20: 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
cd30: 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
cd40: 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
cd50: 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
cd60: 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
cd70: 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
cd80: 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
cd90: 6f 72 2e 0a 2a 2a 20 7b 55 31 37 33 30 39 7d 20  or..** {U17309} 
cda0: 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
cdb0: 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
cdc0: 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
cdd0: 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
cde0: 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
cdf0: 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
ce00: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
ce10: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
ce20: 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
ce30: 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
ce40: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
ce50: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65  ) or sqlite3_fre
ce60: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  e()..**.** {F173
ce70: 31 30 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  10} The sqlite3_
ce80: 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
ce90: 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
cea0: 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
ceb0: 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
cec0: 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
ced0: 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
cee0: 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
cef0: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
cf00: 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
cf10: 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
cf20: 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
cf30: 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
cf40: 20 7b 46 31 37 33 31 31 7d 20 49 66 20 74 68 65   {F17311} If the
cf50: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
cf60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
cf70: 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
cf80: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
cf90: 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
cfa0: 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
cfb0: 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
cfc0: 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
cfd0: 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
cfe0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
cff0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
d000: 2a 2a 20 7b 46 31 37 33 31 32 7d 20 49 66 20 74  ** {F17312} If t
d010: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
d020: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
d030: 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
d040: 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
d050: 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
d060: 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
d070: 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
d080: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
d090: 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
d0a0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
d0b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
d0c0: 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 7b 46 31 37  alloc()..** {F17
d0d0: 33 31 33 7d 20 53 71 6c 69 74 65 33 5f 72 65 61  313} Sqlite3_rea
d0e0: 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
d0f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
d100: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
d110: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
d120: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
d130: 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
d140: 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
d150: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 7b  navailable..** {
d160: 46 31 37 33 31 34 7d 20 49 66 20 4d 20 69 73 20  F17314} If M is 
d170: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
d180: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d190: 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
d1a0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
d1b0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d1c0: 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
d1d0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
d1e0: 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
d1f0: 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
d200: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
d210: 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
d220: 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
d230: 7b 46 31 37 33 31 35 7d 20 49 66 20 73 71 6c 69  {F17315} If sqli
d240: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
d250: 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
d260: 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
d270: 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
d280: 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  freed..**.** {F1
d290: 37 33 38 31 7d 20 54 68 65 20 64 65 66 61 75 6c  7381} The defaul
d2a0: 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
d2b0: 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72  .** of the memor
d2c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
d2d0: 73 79 73 74 65 6d 20 75 73 65 73 20 74 68 65 20  system uses the 
d2e0: 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
d2f0: 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28  c().** and free(
d300: 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  ) provided by th
d310: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
d320: 72 61 72 79 2e 20 7b 46 31 37 33 38 32 7d 20 48  rary. {F17382} H
d330: 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53  owever, if .** S
d340: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
d350: 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f  d with the follo
d360: 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73  wing C preproces
d370: 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20  sor macro.**.** 
d380: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c  <blockquote> SQL
d390: 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
d3a0: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f  <i>NNN</i> </blo
d3b0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77  ckquote>.**.** w
d3c0: 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  here <i>NNN</i> 
d3d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  is an integer, t
d3e0: 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
d3f0: 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61 72  e a static.** ar
d400: 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ray of at least 
d410: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
d420: 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
d430: 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20 66   that array.** f
d440: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
d450: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
d460: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b  ocation needs. {
d470: 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c  END}  Additional
d480: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
d490: 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d 61 79  ator options may
d4a0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
d4b0: 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
d4c0: 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
d4d0: 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
d4e0: 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
d4f0: 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
d500: 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
d510: 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
d520: 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
d530: 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
d540: 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
d550: 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
d560: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
d570: 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
d580: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
d590: 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
d5a0: 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
d5b0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
d5c0: 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73  ors can be.** us
d5d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 45 78 63  ed..**.** <b>Exc
d5e0: 65 70 74 69 6f 6e 3a 3c 2f 62 3e 20 54 68 65 20  eption:</b> The 
d5f0: 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  windows OS inter
d600: 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73  face layer calls
d610: 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
d620: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
d630: 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
d640: 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
d650: 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
d660: 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
d670: 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
d680: 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
d690: 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
d6a0: 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
d6b0: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 77  the particular w
d6c0: 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
d6d0: 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
d6e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
d6f0: 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20  s are detected, 
d700: 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  but.** they are 
d710: 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
d720: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
d730: 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
d740: 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
d750: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
d760: 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  M]..*/.void *sql
d770: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
d780: 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
d790: 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
d7a0: 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
d7b0: 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
d7c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d7d0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
d7e0: 20 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37   Statistics {F17
d7f0: 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64  370}.**.** In ad
d800: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61  dition to the ba
d810: 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61  sic three alloca
d820: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a  tion routines .*
d830: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
d840: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
d850: 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
d860: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
d870: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
d880: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
d890: 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
d8a0: 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  h the SQLite.** 
d8b0: 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73  sources provides
d8c0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
d8d0: 73 68 6f 77 6e 20 68 65 72 65 2e 0a 2a 2a 0a 2a  shown here..**.*
d8e0: 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 65 20 73  * {F17371} The s
d8f0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
d900: 65 64 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ed() routine ret
d910: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
d920: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6d  er of bytes of m
d930: 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
d940: 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
d950: 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
d960: 65 65 64 29 2e 0a 2a 2a 20 7b 46 31 37 33 37 32  eed)..** {F17372
d970: 7d 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  } The value retu
d980: 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
d990: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 20 69 6e  memory_used() in
d9a0: 63 6c 75 64 65 73 0a 2a 2a 20 61 6e 79 20 6f 76  cludes.** any ov
d9b0: 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
d9c0: 53 51 4c 69 74 65 2c 20 62 75 74 20 6e 6f 74 20  SQLite, but not 
d9d0: 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
d9e0: 79 20 74 68 65 0a 2a 2a 20 6c 69 62 72 61 72 79  y the.** library
d9f0: 20 6d 61 6c 6c 6f 63 28 29 20 74 68 61 74 20 62   malloc() that b
da00: 61 63 6b 73 20 74 68 65 20 73 71 6c 69 74 65 33  acks the sqlite3
da10: 5f 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d  _malloc() implem
da20: 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31  entation..** {F1
da30: 37 33 37 33 7d 20 54 68 65 20 73 71 6c 69 74 65  7373} The sqlite
da40: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
da50: 65 72 28 29 20 72 6f 75 74 69 6e 65 73 20 72 65  er() routines re
da60: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6d 61 78  turns the.** max
da70: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
da80: 79 74 65 73 20 74 68 61 74 20 68 61 76 65 20 62  ytes that have b
da90: 65 65 6e 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  een outstanding 
daa0: 73 69 6e 63 65 20 74 68 65 20 0a 2a 2a 20 68 69  since the .** hi
dab0: 67 68 77 61 74 65 72 20 6d 61 72 6b 20 77 61 73  ghwater mark was
dac0: 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 20   last reset..** 
dad0: 7b 46 31 37 33 37 34 7d 20 54 68 65 20 62 79 74  {F17374} The byt
dae0: 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
daf0: 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f   by sqlite3_memo
db00: 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 0a 2a  ry_highwater().*
db10: 2a 20 75 73 65 73 20 74 68 65 20 73 61 6d 65 20  * uses the same 
db20: 62 79 74 65 20 63 6f 75 6e 74 69 6e 67 20 72 75  byte counting ru
db30: 6c 65 73 20 61 73 20 73 71 6c 69 74 65 33 5f 6d  les as sqlite3_m
db40: 65 6d 6f 72 79 5f 75 73 65 64 28 29 2e 0a 2a 2a  emory_used()..**
db50: 20 7b 46 31 37 33 37 35 7d 20 49 66 20 74 68 65   {F17375} If the
db60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
db70: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
db80: 68 77 61 74 65 72 28 29 20 69 73 20 74 72 75 65  hwater() is true
db90: 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 68 69  ,.** then the hi
dba0: 67 68 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  ghwater mark is 
dbb0: 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
dbc0: 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
dbd0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
dbe0: 75 73 65 64 28 29 20 61 6e 64 20 74 68 65 20 70  used() and the p
dbf0: 72 69 6f 72 20 68 69 67 68 77 61 74 65 72 20 6d  rior highwater m
dc00: 61 72 6b 20 28 62 65 66 6f 72 65 20 74 68 65 0a  ark (before the.
dc10: 2a 2a 20 72 65 73 65 74 29 20 69 73 20 72 65 74  ** reset) is ret
dc20: 75 72 6e 65 64 2e 20 20 7b 46 31 37 33 37 36 7d  urned.  {F17376}
dc30: 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
dc40: 65 72 20 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65  er to .** sqlite
dc50: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
dc60: 65 72 28 29 20 69 73 20 7a 65 72 6f 2c 20 74 68  er() is zero, th
dc70: 65 6e 20 74 68 65 20 68 69 67 68 77 61 74 65 72  en the highwater
dc80: 20 6d 61 72 6b 20 69 73 0a 2a 2a 20 75 6e 63 68   mark is.** unch
dc90: 61 6e 67 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65  anged..*/.sqlite
dca0: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
dcb0: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
dcc0: 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
dcd0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
dce0: 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
dcf0: 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
dd00: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
dd10: 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
dd20: 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
dd30: 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12500}.**.** {
dd40: 46 31 32 35 30 31 7d 20 54 68 69 73 20 72 6f 75  F12501} This rou
dd50: 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
dd60: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
dd70: 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
dd80: 69 63 75 6c 61 72 0a 2a 2a 20 64 61 74 61 62 61  icular.** databa
dd90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 73  se connection, s
dda0: 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
ddb0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 7b  irst argument. {
ddc0: 46 31 32 35 30 32 7d 0a 2a 2a 20 54 68 65 20 61  F12502}.** The a
ddd0: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
dde0: 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
ddf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
de00: 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
de10: 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
de20: 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
de30: 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
de40: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
de50: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
de60: 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
de70: 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
de80: 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 7b 46 31  re16_v2()].  {F1
de90: 32 35 30 33 7d 20 41 74 20 76 61 72 69 6f 75 73  2503} At various
dea0: 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
deb0: 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
dec0: 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
ded0: 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
dee0: 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
def0: 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
df00: 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
df10: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
df20: 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
df30: 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
df40: 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
df50: 7b 58 31 32 35 30 34 7d 20 54 68 65 20 61 75 74  {X12504} The aut
df60: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
df70: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
df80: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f 20 61  n SQLITE_OK to a
df90: 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
dfa0: 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
dfb0: 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
dfc0: 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
dfd0: 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
dfe0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
dff0: 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
e000: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
e010: 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
e020: 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
e030: 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
e040: 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
e050: 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
e060: 72 2e 20 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  r.  {END}.**.** 
e070: 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  Depending on the
e080: 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51   action, the [SQ
e090: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64  LITE_IGNORE] and
e0a0: 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72   [SQLITE_DENY] r
e0b0: 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d  eturn.** codes m
e0c0: 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68  ight mean someth
e0d0: 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72  ing different or
e0e0: 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e   they might mean
e0f0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69   the same.** thi
e100: 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74 69  ng.  If the acti
e110: 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70  on is, for examp
e120: 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61  le, to perform a
e130: 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e   delete opertion
e140: 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54  ,.** then [SQLIT
e150: 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53  E_IGNORE] and [S
e160: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68  QLITE_DENY] both
e170: 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74 65   cause the state
e180: 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  ment compilation
e190: 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68  .** to fail with
e1a0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20   an error.  But 
e1b0: 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  if the action is
e1c0: 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63 69   to read a speci
e1d0: 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72  fic column.** fr
e1e0: 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74 61  om a specific ta
e1f0: 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ble, then [SQLIT
e200: 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75  E_DENY] will cau
e210: 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a  se the entire.**
e220: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61   statement to fa
e230: 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49  il but [SQLITE_I
e240: 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73  GNORE] will caus
e250: 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74  e a NULL value t
e260: 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73  o be.** read ins
e270: 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74 75  tead of the actu
e280: 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  al column value.
e290: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20  .**.** {F12510} 
e2a0: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
e2b0: 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
e2c0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
e2d0: 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
e2e0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
e2f0: 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
e300: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
e310: 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
e320: 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73 65   {F12511} The se
e330: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
e340: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
e350: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a  s an integer .**
e360: 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
e370: 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
e380: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
e390: 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
e3a0: 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f  n.** to be autho
e3b0: 72 69 7a 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65  rized. {END} The
e3c0: 20 61 76 61 69 6c 61 62 6c 65 20 61 63 74 69 6f   available actio
e3d0: 6e 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b  n codes are.** [
e3e0: 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f  SQLITE_COPY | do
e3f0: 63 75 6d 65 6e 74 65 64 20 73 65 70 61 72 61 74  cumented separat
e400: 65 6c 79 5d 2e 20 20 7b 46 31 32 35 31 32 7d 20  ely].  {F12512} 
e410: 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
e420: 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d  h sixth.** param
e430: 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
e440: 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
e450: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
e460: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a  s that contain .
e470: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  ** additional de
e480: 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
e490: 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
e4a0: 68 6f 72 69 7a 65 64 2e 20 7b 45 4e 44 7d 0a 2a  horized. {END}.*
e4b0: 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
e4c0: 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
e4d0: 70 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74  preparing SQL st
e4e0: 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
e4f0: 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f   untrusted.** so
e500: 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
e510: 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
e520: 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74  tements do not t
e530: 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
e540: 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61  a.** that they a
e550: 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
e560: 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
e570: 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  hey do not try t
e580: 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c  o.** execute mal
e590: 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
e5a0: 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
e5b0: 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
e5c0: 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
e5d0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
e5e0: 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
e5f0: 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
e600: 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
e610: 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
e620: 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
e630: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
e640: 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
e650: 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
e660: 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
e670: 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
e680: 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
e690: 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
e6a0: 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
e6b0: 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
e6c0: 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
e6d0: 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
e6e0: 62 65 69 6e 67 20 70 72 65 70 61 72 65 64 20 74  being prepared t
e6f0: 68 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  hat disallows ev
e700: 65 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65  erything.** exce
e710: 70 74 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  pt SELECT statem
e720: 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 7b 46  ents.  .**.** {F
e730: 31 32 35 32 30 7d 20 4f 6e 6c 79 20 61 20 73 69  12520} Only a si
e740: 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
e750: 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
e760: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
e770: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
e780: 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
e790: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
e7a0: 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
e7b0: 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
e7c0: 76 69 6f 75 73 20 63 61 6c 6c 2e 20 7b 46 31 32  vious call. {F12
e7d0: 35 32 31 7d 20 20 41 20 4e 55 4c 4c 20 61 75 74  521}  A NULL aut
e7e0: 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68  horizer means th
e7f0: 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74  at no authorizat
e800: 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
e810: 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 7b 46 31  is invoked.  {F1
e820: 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2522} The defaul
e830: 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  t authorizer is 
e840: 4e 55 4c 4c 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  NULL. {END}.**.*
e850: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
e860: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
e870: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
e880: 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b  nly during .** [
e890: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
e8a0: 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
e8b0: 74 73 2e 20 20 7b 46 31 32 35 32 33 7d 20 41 75  ts.  {F12523} Au
e8c0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
e8d0: 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
e8e0: 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
e8f0: 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
e900: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
e910: 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71   {END}.*/.int sq
e920: 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
e930: 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
e940: 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
e950: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
e960: 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
e970: 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
e980: 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
e990: 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
e9a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e9b0: 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
e9c0: 74 75 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35  turn Codes {F125
e9d0: 30 35 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  05}.**.** The [s
e9e0: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
e9f0: 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
ea00: 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
ea10: 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
ea20: 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
ea30: 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
ea40: 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
ea50: 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
ea60: 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
ea70: 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
ea80: 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
ea90: 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
eaa0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
eab0: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
eac0: 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
ead0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
eae0: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
eaf0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
eb00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
eb10: 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
eb20: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
eb30: 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
eb40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
eb50: 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
eb60: 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
eb70: 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
eb80: 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
eb90: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
eba0: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
ebb0: 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
ebc0: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
ebd0: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
ebe0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
ebf0: 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
ec00: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
ec10: 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
ec20: 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69  uthorizer certai
ec30: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
ec40: 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
ec50: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
ec60: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
ec70: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
ec80: 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
ec90: 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
eca0: 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
ecb0: 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
ecc0: 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
ecd0: 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
ece0: 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
ecf0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
ed00: 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
ed10: 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
ed20: 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
ed30: 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
ed40: 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
ed50: 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  e .** authorized
ed60: 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
ed70: 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
ed80: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
ed90: 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  on callback.** f
eda0: 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
edb0: 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
edc0: 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
edd0: 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
ede0: 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
edf0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
ee00: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74  rameter.  The 5t
ee10: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
ee20: 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
ee30: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
ee40: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
ee50: 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
ee60: 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29  temp", .** etc.)
ee70: 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20   if applicable. 
ee80: 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
ee90: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
eea0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
eeb0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
eec0: 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
eed0: 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
eee0: 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
eef0: 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
ef00: 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
ef10: 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
ef20: 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
ef30: 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a  irectly from .**
ef40: 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
ef50: 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
ef60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ef70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
ef80: 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
ef90: 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
efa0: 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
efb0: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
efc0: 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
efd0: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
efe0: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
eff0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
f000: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
f010: 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
f020: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
f030: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
f040: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
f050: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
f060: 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
f070: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
f080: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
f090: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f0a0: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
f0b0: 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
f0c0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
f0d0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
f0e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f0f0: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
f100: 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
f110: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
f120: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
f130: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f140: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
f150: 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
f160: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
f170: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
f180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f190: 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
f1a0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
f1b0: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
f1c0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
f1d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f1e0: 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
f1f0: 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
f200: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
f210: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
f220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
f230: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
f240: 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
f250: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
f260: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
f270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
f280: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
f290: 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
f2a0: 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
f2b0: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
f2c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
f2d0: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
f2e0: 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
f2f0: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
f300: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
f310: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
f320: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
f330: 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
f340: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
f350: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
f360: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
f370: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
f380: 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
f390: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
f3a0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
f3b0: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
f3c0: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
f3d0: 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
f3e0: 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
f3f0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
f400: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
f410: 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
f420: 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
f430: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
f440: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
f450: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
f460: 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
f470: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
f480: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
f490: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
f4a0: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
f4b0: 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
f4c0: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
f4d0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
f4e0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
f4f0: 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
f500: 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
f510: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
f520: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
f530: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
f540: 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
f550: 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
f560: 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
f570: 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
f580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f590: 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
f5a0: 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
f5b0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
f5c0: 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
f5d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f5e0: 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
f5f0: 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
f600: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
f610: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
f620: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f630: 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
f640: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55        22   /* NU
f650: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
f660: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
f670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f680: 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
f690: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
f6a0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
f6b0: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
f6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f6d0: 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
f6e0: 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
f6f0: 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
f700: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
f710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
f720: 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
f730: 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
f740: 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
f750: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
f760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
f770: 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
f780: 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
f790: 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
f7a0: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
f7b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
f7c0: 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
f7d0: 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
f7e0: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
f7f0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
f800: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
f810: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
f820: 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
f830: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
f840: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
f850: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
f860: 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
f870: 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
f880: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
f890: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
f8a0: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
f8b0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
f8c0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
f8d0: 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
f8e0: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
f8f0: 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
f900: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
f910: 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61    /* Function Na
f920: 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
f930: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
f940: 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
f950: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
f960: 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
f970: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
f980: 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
f990: 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
f9a0: 63 74 69 6f 6e 73 20 7b 46 31 32 32 39 30 7d 0a  ctions {F12290}.
f9b0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
f9c0: 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
f9d0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
f9e0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
f9f0: 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
fa00: 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
fa10: 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
fa20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
fa30: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 31 7d 20 54  **.** {F12291} T
fa40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
fa50: 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
fa60: 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
fa70: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
fa80: 20 61 74 20 74 68 65 20 66 69 72 73 74 20 5b 73   at the first [s
fa90: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
faa0: 6f 72 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  or the evaluatio
fab0: 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  n of an SQL stat
fac0: 65 6d 65 6e 74 2e 0a 2a 2a 20 7b 46 31 32 32 39  ement..** {F1229
fad0: 32 7d 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  2} Only a single
fae0: 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
faf0: 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
fb00: 64 20 61 74 20 61 20 74 69 6d 65 2e 0a 2a 2a 20  d at a time..** 
fb10: 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
fb20: 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 76 65  ite3_trace() ove
fb30: 72 72 69 64 65 73 20 74 68 65 20 70 72 65 76 69  rrides the previ
fb40: 6f 75 73 2e 20 20 7b 46 31 32 32 39 33 7d 20 41  ous.  {F12293} A
fb50: 0a 2a 2a 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  .** NULL callbac
fb60: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  k for sqlite3_tr
fb70: 61 63 65 28 29 20 64 69 73 61 62 6c 65 73 20 74  ace() disables t
fb80: 72 61 63 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b  racing. .**.** {
fb90: 46 31 32 32 39 35 7d 20 54 68 65 20 63 61 6c 6c  F12295} The call
fba0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
fbb0: 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
fbc0: 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
fbd0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
fbe0: 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
fbf0: 74 20 66 69 6e 69 73 68 65 73 20 61 6e 64 20 69  t finishes and i
fc00: 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72  ncludes.** infor
fc10: 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f  mation on how lo
fc20: 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
fc30: 74 20 72 61 6e 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a  t ran.{END}.**.*
fc40: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
fc50: 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69  _profile() API i
fc60: 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
fc70: 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
fc80: 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75  tal and.** is su
fc90: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e  bject to change.
fca0: 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
fcb0: 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
fcc0: 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
fcd0: 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
fce0: 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
fcf0: 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
fd00: 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
fd10: 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
fd20: 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
fd30: 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
fd40: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
fd50: 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
fd60: 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
fd70: 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a  cks {F12910}.**.
fd80: 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 69 73  ** {F12911} This
fd90: 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
fda0: 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
fdb0: 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
fdc0: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
fdd0: 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
fde0: 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
fdf0: 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
fe00: 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
fe10: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
fe20: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
fe30: 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
fe40: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
fe50: 5d 2e 20 7b 45 4e 44 7d 20 20 41 6e 20 65 78 61  ]. {END}  An exa
fe60: 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
fe70: 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  s .** interface 
fe80: 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
fe90: 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
fea0: 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
feb0: 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68  *.** {F12912} Th
fec0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
fed0: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
fee0: 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
fef0: 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
ff00: 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72  ne opcodes, wher
ff10: 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
ff20: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
ff30: 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  is function..** 
ff40: 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f  {F12913} The pro
ff50: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
ff60: 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
ff70: 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
ff80: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
ff90: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  this function. {
ffa0: 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72  F12914} The four
ffb0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
ffc0: 68 69 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  his.** function 
ffd0: 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74 65  is a void pointe
ffe0: 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
fff0: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
10000 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65 61  k.** function ea
10010 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
10020 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  voked. {END}.**.
10030 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61  ** {F12915} If a
10040 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
10050 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
10060 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a  te3_step()], or.
10070 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
10080 74 61 62 6c 65 28 29 5d 20 72 65 73 75 6c 74 73  table()] results
10090 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e   in fewer than N
100a0 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65   opcodes being e
100b0 78 65 63 75 74 65 64 2c 0a 2a 2a 20 74 68 65 6e  xecuted,.** then
100c0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
100d0 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20  llback is never 
100e0 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a  invoked. {END}.*
100f0 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20 4f  * .** {F12916} O
10100 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
10110 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66  gress callback f
10120 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
10130 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61  egistered for ea
10140 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ch.** open datab
10150 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
10160 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73   Every call to s
10170 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
10180 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65  handler().** ove
10190 72 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75  rwrites the resu
101a0 6c 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69  lts of the previ
101b0 6f 75 73 20 63 61 6c 6c 2e 20 7b 46 31 32 39 31  ous call. {F1291
101c0 37 7d 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65 20  7}.** To remove 
101d0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
101e0 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 68 65 72  lback altogether
101f0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 73 20 74  , pass NULL as t
10200 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
10210 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
10220 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ction. {END}.**.
10230 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74  ** {F12918} If t
10240 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
10250 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72  back returns a r
10260 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e  esult other than
10270 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   0, then.** the 
10280 63 75 72 72 65 6e 74 20 71 75 65 72 79 20 69 73  current query is
10290 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 74 65 72   immediately ter
102a0 6d 69 6e 61 74 65 64 20 61 6e 64 20 61 6e 79 20  minated and any 
102b0 64 61 74 61 62 61 73 65 20 63 68 61 6e 67 65 73  database changes
102c0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  .** rolled back.
102d0 20 7b 46 31 32 39 31 39 7d 0a 2a 2a 20 54 68 65   {F12919}.** The
102e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71 6c   containing [sql
102f0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
10300 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
10310 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  or.** [sqlite3_g
10320 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c 6c  et_table()] call
10330 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
10340 49 4e 54 45 52 52 55 50 54 2e 20 7b 45 4e 44 7d  INTERRUPT. {END}
10350 20 20 54 68 69 73 20 66 65 61 74 75 72 65 0a 2a    This feature.*
10360 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 66  * can be used, f
10370 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 69  or example, to i
10380 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 22 43 61  mplement the "Ca
10390 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
103a0 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 64 69  a.** progress di
103b0 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20 47 55  alog box in a GU
103c0 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  I..*/.void sqlit
103d0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
103e0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
103f0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
10400 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
10410 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
10420 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
10430 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31  e Connection {F1
10440 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2700}.**.** {F12
10450 37 30 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69  701} These routi
10460 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
10470 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
10480 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69   whose name.** i
10490 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 66  s given by the f
104a0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
104b0 2e 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68  ..** {F12702} Th
104c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
104d0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
104e0 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66  ed as UTF-8.** f
104f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
10500 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
10510 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20  _open_v2()] and 
10520 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20  as UTF-16.** in 
10530 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
10540 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74  order for [sqlit
10550 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
10560 20 7b 46 31 32 37 30 33 7d 20 41 6e 20 5b 73 71   {F12703} An [sq
10570 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69  lite3*] handle i
10580 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  s returned in *p
10590 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20  pDb, even.** if 
105a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
105b0 20 20 7b 46 31 32 37 32 33 7d 20 28 45 78 63 65    {F12723} (Exce
105c0 70 74 69 6f 6e 3a 20 69 66 20 53 51 4c 69 74 65  ption: if SQLite
105d0 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f   is unable.** to
105e0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
105f0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
10600 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61  lite3] object, a
10610 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65   NULL will.** be
10620 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
10630 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
10640 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
10650 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
10660 2e 29 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 49  .).** {F12704} I
10670 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
10680 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
10690 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75 63   created).** suc
106a0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 20  cessfully, then 
106b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
106c0 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 32 37 30  eturned.  {F1270
106d0 35 7d 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a  5} Otherwise an.
106e0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ** error code is
106f0 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 32   returned.  {F12
10700 37 30 36 7d 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  706} The.** [sql
10710 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
10720 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
10730 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73  g16()]  routines
10740 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
10750 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
10760 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
10770 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
10780 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   error..**.** {F
10790 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75  12707} The defau
107a0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
107b0 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
107c0 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
107d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
107e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
107f0 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c  en_v2()] is call
10800 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
10810 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
10820 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b 73 71  yte order if [sq
10830 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
10840 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  is used..**.** {
10850 46 31 32 37 30 38 7d 20 57 68 65 74 68 65 72 20  F12708} Whether 
10860 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
10870 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
10880 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
10890 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
108a0 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
108b0 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f  te3*] handle sho
108c0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
108d0 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a 2a 2a  by passing it.**
108e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
108f0 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
10900 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
10910 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  red..**.** {F127
10920 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
10930 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
10940 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
10950 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10960 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ] .** except tha
10970 74 20 70 72 6f 76 69 64 65 73 20 74 77 6f 20 61  t provides two a
10980 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
10990 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
109a0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
109b0 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
109c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
109d0 20 20 7b 46 31 32 37 31 30 7d 20 54 68 65 20 66    {F12710} The f
109e0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63  lags parameter c
109f0 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a  an be.** one of:
10a00 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
10a10 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
10a20 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c  N_READONLY].** <
10a30 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
10a40 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20  N_READWRITE].** 
10a50 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
10a60 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
10a70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
10a80 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ATE].** </ol>.**
10a90 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 54 68 65  .** {F12711} The
10aa0 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65   first value ope
10ab0 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ns the database 
10ac0 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 7b  read-only. .** {
10ad0 46 31 32 37 31 32 7d 20 49 66 20 74 68 65 20 64  F12712} If the d
10ae0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
10af0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
10b00 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
10b10 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 7b 46 31 32  eturned..** {F12
10b20 37 31 33 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  713} The second 
10b30 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  option opens.** 
10b40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
10b50 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
10b60 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
10b70 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c  , or reading onl
10b80 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66  y if.** if the f
10b90 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
10ba0 74 65 63 74 65 64 2e 20 20 7b 46 31 32 37 31 34  tected.  {F12714
10bb0 7d 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65  } In either case
10bc0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
10bd0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
10be0 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ist or an error 
10bf0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46  is returned.  {F
10c00 31 32 37 31 35 7d 20 54 68 65 20 74 68 69 72 64  12715} The third
10c10 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73   option.** opens
10c20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
10c30 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
10c40 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74 65  iting and create
10c50 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73 0a  s it if it does.
10c60 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  ** not already e
10c70 78 69 73 74 2e 20 7b 46 31 32 37 31 36 7d 0a 2a  xist. {F12716}.*
10c80 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69  * The third opti
10c90 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20  ons is behavior 
10ca0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
10cb0 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  sed for [sqlite3
10cc0 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  _open()].** and 
10cd0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
10ce0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  )]..**.** {F1271
10cf0 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  7} If the filena
10d00 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
10d10 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74  , then an privat
10d20 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  e.** in-memory d
10d30 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74  atabase is creat
10d40 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
10d50 63 74 69 6f 6e 2e 20 7b 46 31 32 37 31 38 7d 20  ction. {F12718} 
10d60 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a  This in-memory.*
10d70 2a 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  * database will 
10d80 76 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20  vanish when the 
10d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10da0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 7b  ion is closed. {
10db0 45 4e 44 7d 20 20 46 75 74 75 72 65 0a 2a 2a 20  END}  Future.** 
10dc0 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
10dd0 65 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65  e might make use
10de0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
10df0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
10e00 0a 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77  .** that begin w
10e10 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
10e20 61 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 65  acter.  It is re
10e30 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a  commended that .
10e40 2a 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ** when a databa
10e50 73 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c  se filename real
10e60 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
10e70 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79  th.** ":" that y
10e80 6f 75 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ou prefix the fi
10e90 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
10ea0 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22  thname like "./"
10eb0 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62   to.** avoid amb
10ec0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  iguity..**.** {F
10ed0 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69  12719} If the fi
10ee0 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
10ef0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
10f00 61 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72  a private tempor
10f10 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
10f20 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
10f30 63 72 65 61 74 65 64 2e 20 20 7b 46 31 32 37 32  created.  {F1272
10f40 30 7d 20 54 68 69 73 20 70 72 69 76 61 74 65 20  0} This private 
10f50 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
10f60 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
10f70 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
10f80 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
10f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
10fa0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  closed..**.** {F
10fb0 31 32 37 32 31 7d 20 54 68 65 20 66 6f 75 72 74  12721} The fourt
10fc0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
10fd0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
10fe0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
10ff0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
11000 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
11010 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
11020 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a  rating system .*
11030 2a 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  * interface that
11040 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
11050 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
11060 75 6c 64 20 75 73 65 2e 20 20 7b 46 31 32 37 32  uld use.  {F1272
11070 32 7d 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  2} If the.** fou
11080 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
11090 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
110a0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
110b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a   [sqlite3_vfs].*
110c0 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  * object is used
110d0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 3c 62  . {END}.**.** <b
110e0 3e 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73  >Note to windows
110f0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
11100 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
11110 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
11120 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b  argument.** of [
11130 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
11140 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
11150 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20  n_v2()] must be 
11160 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
11170 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
11180 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
11190 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
111a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
111b0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
111c0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
111d0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
111e0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
111f0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
11200 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
11210 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
11220 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  en_v2()]..*/.int
11230 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
11240 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
11250 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
11260 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
11270 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
11280 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
11290 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
112a0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
112b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
112c0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
112d0 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
112e0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
112f0 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
11300 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
11310 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
11320 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
11330 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
11340 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
11350 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
11360 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
11370 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
11380 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
11390 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
113a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
113b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
113c0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
113d0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
113e0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
113f0 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
11400 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
11410 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
11420 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11430 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
11440 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31 32  nd Messages {F12
11450 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  800}.**.** {F128
11460 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
11470 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
11480 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
11490 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  numeric.** [SQLI
114a0 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
114b0 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ode] or [SQLITE_
114c0 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
114d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
114e0 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f  e].** for the mo
114f0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
11500 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
11510 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
11520 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d  * with [sqlite3]
11530 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 7b 55   handle 'db'. {U
11540 31 32 38 30 32 7d 20 49 66 20 61 20 70 72 69 6f  12802} If a prio
11550 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
11560 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73  d but the.** mos
11570 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
11580 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
11590 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
115a0 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
115b0 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66  de().** is undef
115c0 69 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ined. {END}.**.*
115d0 2a 20 7b 46 31 32 38 30 33 7d 20 54 68 65 20 73  * {F12803} The s
115e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
115f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
11600 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
11610 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
11620 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
11630 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
11640 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
11650 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
11660 69 76 65 6c 79 2e 0a 2a 2a 20 7b 46 31 32 38 30  ively..** {F1280
11670 34 7d 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  4} Memory to hol
11680 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
11690 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
116a0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
116b0 2e 0a 2a 2a 20 7b 55 31 32 38 30 35 7d 20 54 68  ..** {U12805} Th
116c0 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79  e .** string may
116d0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
116e0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
116f0 79 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  y subsequent cal
11700 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20  ls to SQLite.** 
11710 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
11720 6f 6e 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ons. {END}.**.**
11730 20 7b 46 31 32 38 30 36 7d 20 43 61 6c 6c 73 20   {F12806} Calls 
11740 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f  to many sqlite3_
11750 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74 20  * functions set 
11760 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  the error code a
11770 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 74  nd.** string ret
11780 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
11790 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
117a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
117b0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
117c0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 6f 76  3_errmsg16()] ov
117d0 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70 72  erwriting the pr
117e0 65 76 69 6f 75 73 20 76 61 6c 75 65 73 2e 20 20  evious values.  
117f0 7b 46 31 32 38 30 37 7d 0a 2a 2a 20 45 78 63 65  {F12807}.** Exce
11800 70 74 2c 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  pt, calls to [sq
11810 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
11820 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  ,.** [sqlite3_er
11830 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
11840 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
11850 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  ] themselves do 
11860 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a  not affect the.*
11870 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74  * results of fut
11880 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e  ure invocations.
11890 20 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73    {F12808} Calls
118a0 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73   to API routines
118b0 20 74 68 61 74 0a 2a 2a 20 64 6f 20 6e 6f 74 20   that.** do not 
118c0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
118d0 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 20 5b  code (example: [
118e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
118f0 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a  nt()]) do not.**
11900 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f   change the erro
11910 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20  r code returned 
11920 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  by this routine.
11930 20 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72    {F12809} Inter
11940 66 61 63 65 73 20 74 68 61 74 0a 2a 2a 20 61 72  faces that.** ar
11950 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64  e not associated
11960 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63   with a specific
11970 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11980 74 69 6f 6e 20 28 65 78 61 6d 70 6c 65 73 3a 0a  tion (examples:.
11990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  ** [sqlite3_mpri
119a0 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ntf()] or [sqlit
119b0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
119c0 5f 63 61 63 68 65 28 29 5d 20 64 6f 20 6e 6f 74  _cache()] do not
119d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
119e0 65 74 75 72 6e 20 63 6f 64 65 2e 20 7b 45 4e 44  eturn code. {END
119f0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 31 30 7d  }.**.** {F12810}
11a00 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 68   Assuming no oth
11a10 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 73  er intervening s
11a20 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
11a30 6c 73 20 61 72 65 20 6d 61 64 65 2c 0a 2a 2a 20  ls are made,.** 
11a40 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72  the error code r
11a50 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
11a60 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  function is asso
11a70 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11a80 73 61 6d 65 0a 2a 2a 20 65 72 72 6f 72 20 61 73  same.** error as
11a90 20 74 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   the strings ret
11aa0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
11ab0 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
11ac0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
11ad0 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
11ae0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
11af0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
11b00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
11b10 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
11b20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
11b30 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
11b40 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
11b50 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
11b60 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
11b70 46 31 33 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e  F13000}.**.** In
11b80 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
11b90 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 20  bject represent 
11ba0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
11bb0 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20  ments.  This.** 
11bc0 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
11bd0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
11be0 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
11bf0 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20  a .** "compiled 
11c00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
11c10 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
11c20 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a  tatement"..** .*
11c30 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
11c40 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
11c50 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
11c60 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
11c70 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
11c80 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
11c90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
11ca0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
11cb0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
11cc0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
11cd0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
11ce0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
11cf0 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  rs using.**     
11d00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
11d10 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
11d20 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d  nd_* interfaces]
11d30 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
11d40 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
11d50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
11d60 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
11d70 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
11d80 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
11d90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
11da0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
11db0 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
11dc0 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
11dd0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
11de0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
11df0 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
11e00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
11e10 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
11e20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
11e30 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
11e40 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
11e50 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
11e60 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
11e70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
11e80 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
11e90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
11ea0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
11eb0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
11ec0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
11ed0 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a  tement {F13010}.
11ee0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
11ef0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
11f00 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
11f10 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
11f20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
11f30 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
11f40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
11f50 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31  . .**.** {F13011
11f60 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
11f70 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20  ment "db" is an 
11f80 5b 73 71 6c 69 74 65 33 20 7c 20 53 51 4c 69 74  [sqlite3 | SQLit
11f90 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
11fa0 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  e] .** obtained 
11fb0 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c  from a prior cal
11fc0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
11fd0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
11fe0 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  open_v2()].** or
11ff0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
12000 28 29 5d 2e 20 7b 46 31 33 30 31 32 7d 0a 2a 2a  ()]. {F13012}.**
12010 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
12020 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74  ment "zSql" is t
12030 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
12040 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
12050 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
12060 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
12070 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
12080 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
12090 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
120a0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
120b0 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20   uses UTF-8 and 
120c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
120d0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
120e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
120f0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45  * use UTF-16. {E
12100 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  ND}.**.** {F1301
12110 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
12120 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
12130 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  .** than zero, t
12140 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
12150 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
12160 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
12170 2e 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66  ..** {F13014} If
12180 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
12190 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
121a0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
121b0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74  umber of .** byt
121c0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
121d0 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
121e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
121f0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
12200 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
12210 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
12220 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 20  0' character or 
12230 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e 42  .** until the nB
12240 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
12250 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
12260 73 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  st. {END}.**.** 
12270 7b 46 31 33 30 31 35 7d 20 2a 70 7a 54 61 69 6c  {F13015} *pzTail
12280 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
12290 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
122a0 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64  yte past the end
122b0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
122c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
122d0 6e 20 7a 53 71 6c 2e 20 20 54 68 69 73 20 72 6f  n zSql.  This ro
122e0 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69  utine only compi
122f0 6c 65 73 20 74 68 65 20 66 69 72 73 74 20 73 74  les the first st
12300 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53  atement.** in zS
12310 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
12320 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
12330 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  to what remains 
12340 75 6e 63 6f 6d 70 69 6c 65 64 2e 20 7b 45 4e 44  uncompiled. {END
12350 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d  }.**.** {F13016}
12360 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
12370 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
12380 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c  ompiled .** [sql
12390 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
123a0 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74  statement struct
123b0 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ure] that can be
123c0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
123d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
123e0 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
123f0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
12400 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a  ppStmt may be.**
12410 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 7b   set to NULL.  {
12420 46 31 33 30 31 37 7d 20 49 66 20 74 68 65 20 69  F13017} If the i
12430 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
12440 6e 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ned no SQL (if t
12450 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61  he input.** is a
12460 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  nd empty string 
12470 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
12480 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
12490 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55  t to NULL..** {U
124a0 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69  13018} The calli
124b0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
124c0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
124d0 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20  deleting the.** 
124e0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
124f0 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20  tement.** using 
12500 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
12510 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
12520 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
12530 69 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  it..**.** {F1301
12540 39 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  9} On success, [
12550 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
12560 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
12570 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  se an .** [SQLIT
12580 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
12590 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
125a0 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  d. {END}.**.** T
125b0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
125c0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
125d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
125e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
125f0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
12600 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
12610 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
12620 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
12630 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
12640 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
12650 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
12660 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
12670 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 7b 46  scouraged..** {F
12680 31 33 30 32 30 7d 20 49 6e 20 74 68 65 20 22 76  13020} In the "v
12690 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
126a0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
126b0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
126c0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
126d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
126e0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
126f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a   copy of the .**
12700 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
12710 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63  xt. {END} This c
12720 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
12730 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
12740 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
12750 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20  e a differently 
12760 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a  in two ways:.**.
12770 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 7b  ** <ol>.** <li>{
12780 46 31 33 30 32 32 7d 0a 2a 2a 20 49 66 20 74 68  F13022}.** If th
12790 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
127a0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
127b0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
127c0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
127d0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
127e0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
127f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
12800 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
12810 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
12820 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
12830 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
12840 20 61 67 61 69 6e 2e 20 7b 46 31 32 30 32 33 7d   again. {F12023}
12850 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68   If the schema h
12860 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a  as changed in.**
12870 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65   a way that make
12880 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
12890 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c  no longer valid,
128a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
128b0 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20  ] will still.** 
128c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53  return [SQLITE_S
128d0 43 48 45 4d 41 5d 2e 20 20 7b 45 4e 44 7d 20 42  CHEMA].  {END} B
128e0 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
128f0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 0a  gacy behavior, .
12900 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ** [SQLITE_SCHEM
12910 41 5d 20 69 73 20 6e 6f 77 20 61 20 66 61 74 61  A] is now a fata
12920 6c 20 65 72 72 6f 72 2e 20 20 7b 46 31 32 30 32  l error.  {F1202
12930 34 7d 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73  4} Calling.** [s
12940 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
12950 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
12960 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
12970 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
12980 7b 46 31 32 30 32 35 7d 20 4e 6f 74 65 3a 20 75  {F12025} Note: u
12990 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
129a0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
129b0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
129c0 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
129d0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
129e0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
129f0 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a  ] return. {END}.
12a00 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
12a10 6c 69 3e 0a 2a 2a 20 7b 46 31 33 30 33 30 7d 20  li>.** {F13030} 
12a20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
12a30 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74  curs, .** [sqlit
12a40 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
12a50 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
12a60 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b  e detailed .** [
12a70 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
12a80 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
12a90 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
12aa0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
12ab0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20   result codes]. 
12ac0 20 7b 46 31 33 30 33 31 7d 0a 2a 2a 20 54 68 65   {F13031}.** The
12ad0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
12ae0 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74   was that [sqlit
12af0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
12b00 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
12b10 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  eneric.** [SQLIT
12b20 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
12b30 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75  code and you wou
12b40 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
12b50 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
12b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
12b70 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  et()] in order t
12b80 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
12b90 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
12ba0 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 7b  he problem..** {
12bb0 46 31 33 30 33 32 7d 0a 2a 2a 20 57 69 74 68 20  F13032}.** With 
12bc0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
12bd0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
12be0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
12bf0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
12c00 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20   is.** returned 
12c10 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 7b 45 4e  immediately. {EN
12c20 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  D}.** </li>.** <
12c30 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
12c40 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
12c50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
12c60 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
12c70 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
12c80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
12c90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
12ca0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
12cb0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
12cc0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
12cd0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
12ce0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
12cf0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
12d00 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
12d10 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
12d20 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
12d30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
12d40 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
12d50 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
12d60 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
12d70 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
12d80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
12d90 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
12da0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
12db0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
12dc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
12dd0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
12de0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
12df0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
12e00 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
12e10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
12e20 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
12e30 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
12e40 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
12e50 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
12e60 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
12e70 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
12e80 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
12e90 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
12ea0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
12eb0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
12ec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
12ed0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
12ee0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
12ef0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
12f00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
12f10 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
12f20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
12f30 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
12f40 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
12f50 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
12f60 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
12f70 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
12f80 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
12f90 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
12fa0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
12fb0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
12fc0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
12fd0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
12fe0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
12ff0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
13000 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
13010 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
13020 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
13030 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
13040 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
13050 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
13060 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
13070 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
13080 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
13090 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
130a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
130b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
130c0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
130d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
130e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
130f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
13100 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
13110 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
13120 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
13130 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
13140 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
13150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20  ./*.** CAPIREF: 
13160 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
13170 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30  ment SQL {F13100
13180 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d  }.**.** {F13101}
13190 20 49 66 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   If the compiled
131a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 70   SQL statement p
131b0 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75  assed as an argu
131c0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
131d0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
131e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
131f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
13200 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
13210 32 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  2()],.** then th
13220 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
13230 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13240 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
13250 65 64 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e  ed string.** con
13260 74 61 69 6e 69 6e 67 20 61 20 63 6f 70 79 20 6f  taining a copy o
13270 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53  f the original S
13280 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 7b 46  QL statement. {F
13290 31 33 31 30 32 7d 20 54 68 65 0a 2a 2a 20 70 6f  13102} The.** po
132a0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
132b0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
132c0 6e 74 0a 2a 2a 20 69 73 20 64 65 6c 65 74 65 64  nt.** is deleted
132d0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
132e0 69 6e 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 7b 46  inalize()..** {F
132f0 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
13300 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
13310 6c 69 74 65 33 5f 73 71 6c 28 29 20 69 73 20 61  lite3_sql() is a
13320 6c 77 61 79 73 20 55 54 46 38 20 65 76 65 6e 0a  lways UTF8 even.
13330 2a 2a 20 69 66 20 61 20 55 54 46 31 36 20 73 74  ** if a UTF16 st
13340 72 69 6e 67 20 77 61 73 20 6f 72 69 67 69 6e 61  ring was origina
13350 6c 6c 79 20 65 6e 74 65 72 65 64 20 75 73 69 6e  lly entered usin
13360 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
13370 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
13380 2a 20 7b 46 31 33 31 30 34 7d 20 49 66 20 74 68  * {F13104} If th
13390 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
133a0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
133b0 69 74 68 65 72 20 6f 66 20 74 68 65 20 6c 65 67  ither of the leg
133c0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
133d0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
133e0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
133f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
13400 74 68 69 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  this.** function
13410 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
13420 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
13430 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
13440 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
13450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13460 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79    Dynamically Ty
13470 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
13480 20 20 7b 46 31 35 30 30 30 7d 0a 2a 2a 0a 2a 2a    {F15000}.**.**
13490 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
134a0 61 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20  amic typing for 
134b0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
134c0 6f 72 65 73 2e 20 20 56 61 6c 75 65 73 20 63 61  ores.  Values ca
134d0 6e 20 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72  n .** be integer
134e0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
134f0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
13500 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
13510 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73 73  L.  When.** pass
13520 69 6e 67 20 61 72 6f 75 6e 64 20 76 61 6c 75 65  ing around value
13530 73 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61  s internally, ea
13540 63 68 20 76 61 6c 75 65 20 69 73 20 72 65 70 72  ch value is repr
13550 65 73 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61 6e  esented as.** an
13560 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13570 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
13580 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
13590 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
135a0 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
135b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 51  ** CAPI3REF:  SQ
135c0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
135d0 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30  xt Object {F1600
135e0 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  1}.**.** The con
135f0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
13600 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
13610 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
13620 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
13630 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
13640 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  .  A pointer to 
13650 73 75 63 68 20 61 6e 20 6f 62 6a 65 63 74 20 69  such an object i
13660 73 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 70  s the.** first p
13670 61 72 61 6d 65 74 65 72 20 74 6f 20 75 73 65 72  arameter to user
13680 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
13690 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64  ctions..*/.typed
136a0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
136b0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
136c0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
136d0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e  * CAPI3REF:  Bin
136e0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
136f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
13700 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a  ts {F13500}.**.*
13710 2a 20 7b 46 31 33 35 30 31 7d 20 49 6e 20 74 68  * {F13501} In th
13720 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
13730 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
13740 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
13750 64 20 69 74 73 0a 2a 2a 20 76 61 72 69 61 6e 74  d its.** variant
13760 73 2c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6c  s, one or more l
13770 69 74 65 72 61 6c 73 20 63 61 6e 20 62 65 20 72  iterals can be r
13780 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72 61  eplace by a para
13790 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20  meter in one.** 
137a0 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a  of these forms:.
137b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
137c0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
137d0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41 41  NNN.** <li>  :AA
137e0 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41 0a  A.** <li>  @AAA.
137f0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
13800 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
13810 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f  the parameter fo
13820 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  rms shown above 
13830 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
13840 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41 41  r literal,.** AA
13850 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  A is an alphanum
13860 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 20  eric identifier 
13870 61 6e 64 20 56 56 56 20 69 73 20 61 20 76 61 72  and VVV is a var
13880 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f 72  iable name accor
13890 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ding.** to the s
138a0 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20 74  yntax rules of t
138b0 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d 69  he TCL programmi
138c0 6e 67 20 6c 61 6e 67 75 61 67 65 2e 20 7b 45 4e  ng language. {EN
138d0 44 7d 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  D}.** The values
138e0 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
138f0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
13900 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
13910 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e  r names").** can
13920 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
13930 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
13940 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
13950 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
13960 7b 46 31 33 35 30 32 7d 20 54 68 65 20 66 69 72  {F13502} The fir
13970 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
13980 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
13990 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c 77  *() routines alw
139a0 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ays.** is a poin
139b0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
139c0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
139d0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
139e0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
139f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
13a00 76 61 72 69 61 6e 74 73 2e 20 20 7b 46 31 33 35  variants.  {F135
13a10 30 33 7d 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a  03} The second.*
13a20 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  * argument is th
13a30 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70  e index of the p
13a40 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
13a50 65 74 2e 20 20 7b 46 31 33 35 30 34 7d 20 54 68  et.  {F13504} Th
13a60 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
13a70 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
13a80 78 20 6f 66 20 31 2e 20 20 7b 46 31 33 35 30 35  x of 1.  {F13505
13a90 7d 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20  } When the same 
13aa0 6e 61 6d 65 64 0a 2a 2a 20 70 61 72 61 6d 65 74  named.** paramet
13ab0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
13ac0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
13ad0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
13ae0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
13af0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
13b00 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
13b10 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 0a 2a 2a   occurrence. .**
13b20 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20 69 6e   {F13506} The in
13b30 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
13b40 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
13b50 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
13b60 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13b70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
13b80 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65  ame()] API if de
13b90 73 69 72 65 64 2e 20 20 7b 46 31 33 35 30 37 7d  sired.  {F13507}
13ba0 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
13bb0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
13bc0 65 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  es is the value 
13bd0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 7b 46 31 33 35  of NNN..** {F135
13be0 30 38 7d 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  08} The NNN valu
13bf0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
13c00 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70  n 1 and the comp
13c10 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61  ile-time.** para
13c20 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58  meter SQLITE_MAX
13c30 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
13c40 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
13c50 20 39 39 39 29 2e 20 7b 45 4e 44 7d 0a 2a 2a 20   999). {END}.** 
13c60 53 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d  See <a href="lim
13c70 69 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73  its.html">limits
13c80 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64  .html</a> for ad
13c90 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
13ca0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tion..**.** {F13
13cb0 35 30 39 7d 20 54 68 65 20 74 68 69 72 64 20 61  509} The third a
13cc0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
13cd0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
13ce0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 7b  the parameter. {
13cf0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  END}.**.** {F135
13d00 31 30 7d 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20  10} In those.** 
13d10 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
13d20 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
13d30 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
13d40 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
13d50 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65   bytes.** in the
13d60 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
13d70 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
13d80 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65  lue is the numbe
13d90 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
13da0 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74  e.** string, not
13db0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13dc0 68 61 72 61 63 74 65 72 73 2e 20 7b 46 31 33 35  haracters. {F135
13dd0 31 31 7d 20 20 54 68 65 20 6e 75 6d 62 65 72 0a  11}  The number.
13de0 2a 2a 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73  ** of bytes does
13df0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
13e00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
13e10 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73   at the end of s
13e20 74 72 69 6e 67 73 2e 0a 2a 2a 20 7b 46 31 33 35  trings..** {F135
13e30 31 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  12}.** If the fo
13e40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
13e50 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
13e60 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
13e70 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65  ring is.** numbe
13e80 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
13e90 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
13ea0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 7b 45 4e 44  terminator. {END
13eb0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 33 7d  }.**.** {F13513}
13ec0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
13ed0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
13ee0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
13ef0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
13f00 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
13f10 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
13f20 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
13f30 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
13f40 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
13f50 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53 51  ** text after SQ
13f60 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
13f70 64 20 77 69 74 68 20 69 74 2e 20 7b 46 31 33 35  d with it. {F135
13f80 31 34 7d 20 49 66 20 74 68 65 20 66 69 66 74 68  14} If the fifth
13f90 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
13fa0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
13fb0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
13fc0 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72  ], then the libr
13fd0 61 72 79 20 61 73 73 75 6d 65 73 20 74 68 61 74  ary assumes that
13fe0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
13ff0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
14000 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
14010 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
14020 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
14030 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20 49 66 20  .** {F13515} If 
14040 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
14050 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
14060 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
14070 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
14080 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
14090 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
140a0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
140b0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
140c0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
140d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
140e0 65 74 75 72 6e 73 2e 20 7b 45 4e 44 7d 0a 2a 2a  eturns. {END}.**
140f0 0a 2a 2a 20 7b 46 31 33 35 32 30 7d 20 54 68 65  .** {F13520} The
14100 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
14110 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
14120 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
14130 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
14140 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
14150 20 7a 65 72 6f 73 2e 20 20 7b 46 31 33 35 32 31   zeros.  {F13521
14160 7d 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65  } A zeroblob use
14170 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
14180 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
14190 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
141a0 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20  o hold it size) 
141b0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
141c0 67 20 70 72 6f 63 65 73 73 65 64 2e 20 7b 45 4e  g processed. {EN
141d0 44 7d 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  D}.** Zeroblobs 
141e0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
141f0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68  serve as place-h
14200 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
14210 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
14220 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
14230 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  en using .** [sq
14240 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
14250 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42  | increment BLOB
14260 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20   I/O] routines. 
14270 7b 46 31 33 35 32 32 7d 20 41 20 6e 65 67 61 74  {F13522} A negat
14280 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72  ive.** value for
14290 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
142a0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
142b0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 20 7b 45 4e  length BLOB. {EN
142c0 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30  D}.**.** {F13530
142d0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  } The sqlite3_bi
142e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
142f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61  must be called a
14300 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fter.** [sqlite3
14310 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28  _prepare_v2()] (
14320 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
14330 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ) or [sqlite3_re
14340 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65  set()] and.** be
14350 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
14360 65 70 28 29 5d 2e 20 7b 46 31 33 35 33 31 7d 0a  ep()]. {F13531}.
14370 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20  ** Bindings are 
14380 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
14390 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
143a0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
143b0 20 7b 46 31 33 35 33 32 7d 20 55 6e 62 6f 75 6e   {F13532} Unboun
143c0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
143d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
143e0 4e 55 4c 4c 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  NULL. {END}.**.*
143f0 2a 20 7b 46 31 33 35 34 30 7d 20 54 68 65 73 65  * {F13540} These
14400 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
14410 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
14420 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
14430 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
14440 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
14450 6e 67 2e 20 20 7b 46 31 33 35 34 31 7d 20 5b 53  ng.  {F13541} [S
14460 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
14470 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
14480 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
14490 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
144a0 67 65 2e 20 20 7b 46 31 33 35 34 32 7d 20 5b 53  ge.  {F13542} [S
144b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
144c0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
144d0 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 7b 46 31  oc fails..** {F1
144e0 33 35 34 33 7d 20 5b 53 51 4c 49 54 45 5f 4d 49  3543} [SQLITE_MI
144f0 53 55 53 45 5d 20 69 73 20 72 65 74 75 72 6e 65  SUSE] is returne
14500 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
14510 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
14520 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
14530 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
14540 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
14550 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
14560 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
14570 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
14580 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
14590 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
145a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
145b0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
145c0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
145d0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
145e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
145f0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
14600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
14610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
14620 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
14630 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
14640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
14650 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
14660 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
14670 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
14680 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
14690 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
146a0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
146b0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
146c0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
146d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
146e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
146f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
14700 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
14710 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
14720 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
14730 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
14740 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
14750 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
14760 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
14770 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
14780 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
14790 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
147a0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
147b0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
147c0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 73   Host Parameters
147d0 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13600}.**.** 
147e0 7b 46 31 33 36 30 31 7d 20 52 65 74 75 72 6e 20  {F13601} Return 
147f0 74 68 65 20 6c 61 72 67 65 73 74 20 68 6f 73 74  the largest host
14800 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 65 78   parameter index
14810 20 69 6e 20 74 68 65 20 70 72 65 63 6f 6d 70 69   in the precompi
14820 6c 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  led.** statement
14830 20 67 69 76 65 6e 20 61 73 20 74 68 65 20 61 72   given as the ar
14840 67 75 6d 65 6e 74 2e 20 7b 46 31 33 36 30 32 7d  gument. {F13602}
14850 20 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70   When the host p
14860 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 61 72 65  arameters.** are
14870 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 6c 69   of the forms li
14880 6b 65 20 22 3a 41 41 41 22 20 6f 72 20 22 3f 22  ke ":AAA" or "?"
14890 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 79 20 61  ,.** then they a
148a0 72 65 20 61 73 73 69 67 6e 65 64 20 73 65 71 75  re assigned sequ
148b0 65 6e 74 69 61 6c 20 69 6e 63 72 65 61 73 69 6e  ential increasin
148c0 67 20 6e 75 6d 62 65 72 73 20 62 65 67 69 6e 6e  g numbers beginn
148d0 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 6e 65 2c  ing.** with one,
148e0 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65   so the value re
148f0 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
14900 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
14910 72 73 2e 0a 2a 2a 20 7b 46 31 33 36 30 33 7d 20  rs..** {F13603} 
14920 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 68  However.** if th
14930 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72 61  e same host para
14940 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75 73  meter name is us
14950 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
14960 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61 6e  s, each occurran
14970 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 74  ce.** is given t
14980 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20  he same number, 
14990 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  so the value ret
149a0 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63 61  urned in that ca
149b0 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  se is the number
149c0 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 6f  .** of unique ho
149d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
149e0 65 73 2e 20 7b 46 31 33 36 30 34 7d 20 49 66 20  es. {F13604} If 
149f0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
14a00 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
14a10 3f 4e 4e 4e 22 20 61 72 65 20 75 73 65 64 20 28  ?NNN" are used (
14a20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 20  where NNN is an 
14a30 69 6e 74 65 67 65 72 29 20 74 68 65 6e 20 74 68  integer) then th
14a40 65 72 65 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  ere might be.** 
14a50 67 61 70 73 20 69 6e 20 74 68 65 20 6e 75 6d 62  gaps in the numb
14a60 65 72 69 6e 67 20 61 6e 64 20 74 68 65 20 76 61  ering and the va
14a70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
14a80 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
14a90 73 0a 2a 2a 20 74 68 65 20 69 6e 64 65 78 20 6f  s.** the index o
14aa0 66 20 74 68 65 20 68 6f 73 74 20 70 61 72 61 6d  f the host param
14ab0 65 74 65 72 20 77 69 74 68 20 74 68 65 20 6c 61  eter with the la
14ac0 72 67 65 73 74 20 69 6e 64 65 78 20 76 61 6c 75  rgest index valu
14ad0 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  e. {END}.**.** {
14ae0 55 31 33 36 30 35 7d 20 54 68 65 20 70 72 65 70  U13605} The prep
14af0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d  ared statement m
14b00 75 73 74 20 6e 6f 74 20 62 65 20 5b 73 71 6c 69  ust not be [sqli
14b10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
14b20 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20 70 72 69  inalized].** pri
14b30 6f 72 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  or to this routi
14b40 6e 65 20 72 65 74 75 72 6e 69 6e 67 2e 20 20 4f  ne returning.  O
14b50 74 68 65 72 77 69 73 65 20 74 68 65 20 72 65 73  therwise the res
14b60 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
14b70 65 64 0a 2a 2a 20 61 6e 64 20 70 72 6f 62 61 62  ed.** and probab
14b80 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
14b90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
14ba0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
14bb0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
14bc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
14bd0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
14be0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 46  ost Parameter {F
14bf0 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  13620}.**.** {F1
14c00 33 36 32 31 7d 20 54 68 69 73 20 72 6f 75 74 69  3621} This routi
14c10 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
14c20 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65  nter to the name
14c30 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20   of the n-th.** 
14c40 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20 5b  parameter in a [
14c50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
14c60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14c70 74 5d 2e 20 7b 46 31 33 36 32 32 7d 0a 2a 2a 20  t]. {F13622}.** 
14c80 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  Host parameters 
14c90 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a 41 41  of the form ":AA
14ca0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
14cb0 22 24 56 56 56 22 20 68 61 76 65 20 61 20 6e 61  "$VVV" have a na
14cc0 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 74  me.** which is t
14cd0 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 41 22  he string ":AAA"
14ce0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
14cf0 56 56 56 22 2e 20 0a 2a 2a 20 49 6e 20 6f 74 68  VVV". .** In oth
14d00 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
14d10 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
14d20 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e   or "@".** is in
14d30 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
14d40 66 20 74 68 65 20 6e 61 6d 65 2e 20 20 7b 46 31  f the name.  {F1
14d50 33 36 32 33 7d 0a 2a 2a 20 50 61 72 61 6d 65 74  3623}.** Paramet
14d60 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
14d70 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61  "?" or "?NNN" ha
14d80 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  ve no name..**.*
14d90 2a 20 7b 46 31 33 36 32 33 7d 20 54 68 65 20 66  * {F13623} The f
14da0 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d  irst bound param
14db0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
14dc0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
14dd0 2a 0a 2a 2a 20 7b 46 31 33 36 32 34 7d 20 49 66  *.** {F13624} If
14de0 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
14df0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
14e00 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
14e10 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
14e20 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
14e30 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46  is returned.  {F
14e40 31 33 36 32 35 7d 20 54 68 65 20 72 65 74 75 72  13625} The retur
14e50 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
14e60 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 20 55   always in the U
14e70 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
14e80 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
14e90 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
14ea0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
14eb0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
14ec0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
14ed0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
14ee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
14ef0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
14f00 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
14f10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
14f20 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
14f30 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
14f40 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
14f50 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
14f60 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
14f70 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13640}.**.** 
14f80 7b 46 31 33 36 34 31 7d 20 54 68 69 73 20 72 6f  {F13641} This ro
14f90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
14fa0 65 20 69 6e 64 65 78 20 6f 66 20 61 20 68 6f 73  e index of a hos
14fb0 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  t parameter with
14fc0 20 74 68 65 0a 2a 2a 20 67 69 76 65 6e 20 6e 61   the.** given na
14fd0 6d 65 2e 20 20 7b 46 31 33 36 34 32 7d 20 54 68  me.  {F13642} Th
14fe0 65 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63  e name must matc
14ff0 68 20 65 78 61 63 74 6c 79 2e 20 20 7b 46 31 33  h exactly.  {F13
15000 36 34 33 7d 0a 2a 2a 20 49 66 20 6e 6f 20 70 61  643}.** If no pa
15010 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65  rameter with the
15020 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 66   given name is f
15030 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30 2e 0a  ound, return 0..
15040 2a 2a 20 7b 46 31 33 36 34 34 7d 20 50 61 72 61  ** {F13644} Para
15050 6d 65 74 65 72 20 6e 61 6d 65 73 20 6d 75 73 74  meter names must
15060 20 62 65 20 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74   be UTF8..*/.int
15070 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
15080 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
15090 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
150a0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
150b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
150c0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
150d0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
150e0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31  ed Statement {F1
150f0 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  3660}.**.** {F13
15100 36 36 31 7d 20 43 6f 6e 74 72 61 72 79 20 74 6f  661} Contrary to
15110 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
15120 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
15130 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
15140 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20  ot.** reset the 
15150 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
15160 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
15170 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  n a .** [sqlite3
15180 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
15190 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 7b 46 31   statement]. {F1
151a0 33 36 36 32 7d 20 55 73 65 20 74 68 69 73 20 72  3662} Use this r
151b0 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  outine to.** res
151c0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
151d0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
151e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
151f0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
15200 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
15210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
15220 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
15230 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
15240 20 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F13710}.**.** 
15250 7b 46 31 33 37 31 31 7d 20 52 65 74 75 72 6e 20  {F13711} Return 
15260 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
15270 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
15280 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
15290 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   by the .** [sql
152a0 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
152b0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
152c0 6e 74 5d 2e 20 7b 46 31 33 37 31 32 7d 20 54 68  nt]. {F13712} Th
152d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
152e0 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74  ns 0.** if pStmt
152f0 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65   is an SQL state
15300 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
15310 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
15320 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  for .** example 
15330 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f 0a 69  an UPDATE)..*/.i
15340 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
15350 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
15360 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
15370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
15380 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
15390 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
153a0 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  720}.**.** {F137
153b0 32 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e  21} These routin
153c0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
153d0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
153e0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
153f0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
15400 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
15410 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
15420 7b 46 31 33 37 32 32 7d 20 54 68 65 20 73 71 6c  {F13722} The sql
15430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
15440 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
15450 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
15460 72 20 74 6f 20 61 20 55 54 46 38 20 73 74 72 69  r to a UTF8 stri
15470 6e 67 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ng and sqlite3_c
15480 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a  olumn_name16().*
15490 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
154a0 74 65 72 20 74 6f 20 61 20 55 54 46 31 36 20 73  ter to a UTF16 s
154b0 74 72 69 6e 67 2e 20 7b 46 31 33 37 32 33 7d 20  tring. {F13723} 
154c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
154d0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
154e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
154f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15500 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  t] that implemen
15510 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  ts the SELECT st
15520 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  atement..** The 
15530 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15540 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e   is the column n
15550 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
15560 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a  -most column is.
15570 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  ** number 0..**.
15580 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65 20  ** {F13724} The 
15590 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
155a0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
155b0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
155c0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  e .** [sqlite3_s
155d0 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
155e0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
155f0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
15600 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
15610 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
15620 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ext call sqlite3
15630 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
15640 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
15650 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20  _name16().** on 
15660 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
15670 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20  .**.** {F13725} 
15680 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
15690 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
156a0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
156b0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
156c0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
156d0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
156e0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
156f0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
15700 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
15710 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
15720 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
15730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
15740 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
15750 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
15760 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
15770 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
15780 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
15790 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
157a0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
157b0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
157c0 73 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a  sult {F13740}.**
157d0 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 65  .** {F13741} The
157e0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
157f0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
15800 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f  etermine what co
15810 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20  lumn of what.** 
15820 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64  table in which d
15830 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74  atabase a result
15840 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
15850 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f  tement comes fro
15860 6d 2e 0a 2a 2a 20 7b 46 31 33 37 34 32 7d 20 54  m..** {F13742} T
15870 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
15880 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
15890 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
158a0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
158b0 20 65 69 74 68 65 72 20 61 20 55 54 46 38 20 6f   either a UTF8 o
158c0 72 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20  r UTF16 string. 
158d0 20 7b 46 31 33 37 34 33 7d 20 54 68 65 20 5f 64   {F13743} The _d
158e0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
158f0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
15900 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
15910 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
15920 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
15930 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
15940 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
15950 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
15960 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 20 7b  e column name. {
15970 46 31 33 37 34 34 7d 0a 2a 2a 20 54 68 65 20 72  F13744}.** The r
15980 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
15990 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a  s valid until.**
159a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
159b0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
159c0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
159d0 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  royed using.** [
159e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
159f0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
15a00 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
15a10 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
15a20 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
15a30 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
15a40 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20  .**.** {F13745} 
15a50 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
15a60 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
15a70 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
15a80 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
15a90 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
15aa0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
15ab0 2a 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 66  * {F13746} The f
15ac0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
15ad0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
15ae0 61 6c 6c 73 20 69 73 20 61 20 0a 2a 2a 20 5b 73  alls is a .** [s
15af0 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f  qlite3_stmt | co
15b00 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
15b10 6d 65 6e 74 5d 2e 0a 2a 2a 20 7b 46 31 33 37 34  ment]..** {F1374
15b20 37 7d 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  7} These functio
15b30 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
15b40 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
15b50 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
15b60 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73  ned by .** the s
15b70 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
15b80 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
15b90 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
15ba0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 38  t..**.** {F13748
15bb0 7d 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  } If the Nth col
15bc0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
15bd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
15be0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a   an expression.*
15bf0 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e  * or subquery an
15c00 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
15c10 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
15c20 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
15c30 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e  ions.** return N
15c40 55 4c 4c 2e 20 20 7b 46 31 33 37 34 39 7d 20 4f  ULL.  {F13749} O
15c50 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
15c60 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61  eturn the .** na
15c70 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
15c80 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
15c90 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68  le and column th
15ca0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a  at query result.
15cb0 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  ** column was ex
15cc0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
15cd0 0a 2a 2a 20 7b 46 31 33 37 35 30 7d 20 41 73 20  .** {F13750} As 
15ce0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
15cf0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
15d00 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68  e postfixed with
15d10 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
15d20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
15d30 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65  trings, the othe
15d40 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
15d50 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a  rn UTF-8. {END}.
15d60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73  **.** These APIs
15d70 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
15d80 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
15d90 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
15da0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
15db0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
15dc0 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72  N_METADATA prepr
15dd0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
15de0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55  efined..**.** {U
15df0 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f  13751}.** If two
15e00 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
15e10 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
15e20 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
15e30 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
15e40 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
15e50 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
15e60 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
15e70 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
15e80 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
15e90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
15ea0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
15eb0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
15ec0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
15ed0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
15ee0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
15ef0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
15f00 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
15f10 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
15f20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
15f30 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
15f40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
15f50 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
15f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
15f70 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
15f80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
15f90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
15fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
15fb0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
15fc0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
15fd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
15fe0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
15ff0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
16000 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
16010 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
16020 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
16030 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33  uery Result {F13
16040 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  760}.**.** The f
16050 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
16060 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  s a [sqlite3_stm
16070 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
16080 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a   statement]. .**
16090 20 7b 46 31 33 37 36 31 7d 20 49 66 20 74 68 69   {F13761} If thi
160a0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
160b0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
160c0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
160d0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20  lumn of the .** 
160e0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
160f0 73 65 74 20 20 6f 66 20 74 68 61 74 20 53 45 4c  set  of that SEL
16100 45 43 54 20 69 73 20 61 20 74 61 62 6c 65 20 63  ECT is a table c
16110 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
16120 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
16130 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
16140 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
16150 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
16160 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
16170 65 64 2e 20 20 7b 46 31 33 37 36 32 7d 20 49 66  ed.  {F13762} If
16180 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
16190 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
161a0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
161b0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
161c0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
161d0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
161e0 65 64 2e 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20  ed..** {F13763} 
161f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
16200 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
16210 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45  F-8 encoded.  {E
16220 4e 44 7d 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ND} .** For exam
16230 70 6c 65 2c 20 69 6e 20 74 68 65 20 64 61 74 61  ple, in the data
16240 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
16250 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
16260 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
16270 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f  **.** And the fo
16280 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
16290 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  t compiled:.**.*
162a0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
162b0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
162c0 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75  ** Then this rou
162d0 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
162e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
162f0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
16300 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20  econd.** result 
16310 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
16320 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
16330 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
16340 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
16350 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53   (i==0)..**.** S
16360 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
16370 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
16380 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63  ng.  So just bec
16390 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
163a0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
163b0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
163c0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
163d0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
163e0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
163f0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
16400 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
16410 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
16420 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
16430 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
16440 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
16450 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70  not static.  Typ
16460 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
16470 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
16480 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
16490 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
164a0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
164b0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
164c0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
164d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
164e0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
164f0 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a  stmt *, int i);.
16500 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
16510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
16520 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
16530 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a  mt*,int);../* .*
16540 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61  * CAPI3REF:  Eva
16550 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
16560 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30 7d 0a  tement {F13200}.
16570 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b  **.** After an [
16580 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
16590 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  QL statement] ha
165a0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
165b0 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74  with a call.** t
165c0 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  o either [sqlite
165d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
165e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
165f0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
16600 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  o one of.** the 
16610 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
16620 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
16630 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
16640 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
16650 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e  ** then this fun
16660 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61  ction must be ca
16670 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
16680 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
16690 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65  te the .** state
166a0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
166b0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
166c0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
166d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
166e0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
166f0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
16700 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
16710 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
16720 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
16730 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
16740 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16750 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
16760 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
16770 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
16780 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
16790 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
167a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
167b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
167c0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
167d0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
167e0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
167f0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
16800 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
16810 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
16820 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
16830 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
16840 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ed..**.** In the
16850 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61 63   lagacy interfac
16860 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
16870 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
16880 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
16890 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  , .** [SQLITE_DO
168a0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
168b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
168c0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
168d0 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  SUSE]..** With t
168e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
168f0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
16900 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  her [SQLITE_OK |
16910 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
16920 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
16930 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
16940 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d  d result code] m
16950 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
16960 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a   as.** well..**.
16970 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
16980 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
16990 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
169a0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
169b0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
169c0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
169d0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
169e0 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  ob.  If the stat
169f0 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49  ement is a COMMI
16a00 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  T.** or occurs o
16a10 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
16a20 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
16a30 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
16a40 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
16a50 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
16a60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
16a70 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63   a COMMIT and oc
16a80 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a  curs within a.**
16a90 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
16aa0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
16ab0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
16ac0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
16ad0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
16ae0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ing..**.** [SQLI
16af0 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
16b00 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
16b10 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
16b20 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
16b30 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
16b40 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
16b50 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
16b60 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
16b70 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
16b80 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
16b90 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
16ba0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
16bb0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
16bc0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
16bd0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
16be0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
16bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
16c00 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
16c10 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
16c20 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hen .** [SQLITE_
16c30 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROW] is returned
16c40 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
16c50 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
16c60 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f  ready.** for pro
16c70 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 20 63  cessing by the c
16c80 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
16c90 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
16ca0 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  d using.** the [
16cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
16cc0 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65  nt | column acce
16cd0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
16ce0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
16cf0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
16d00 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
16d10 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
16d20 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54  a..** .** [SQLIT
16d30 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
16d40 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
16d50 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
16d60 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
16d70 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
16d80 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
16d90 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
16da0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
16db0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
16dc0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
16dd0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
16de0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
16df0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
16e00 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
16e10 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
16e20 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
16e30 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a   code (example:.
16e40 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
16e50 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
16e60 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
16e70 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
16e80 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
16e90 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
16ea0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
16eb0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
16ec0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
16ed0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
16ee0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
16ef0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
16f00 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
16f10 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
16f20 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
16f30 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
16f40 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
16f50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
16f60 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
16f70 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
16f80 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
16f90 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
16fa0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
16fb0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
16fc0 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
16fd0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
16fe0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
16ff0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17000 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
17010 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
17020 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  d .** previously
17030 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
17040 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
17050 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
17060 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
17070 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
17080 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
17090 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
170a0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
170b0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
170c0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
170d0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
170e0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
170f0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
17100 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
17110 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a  y interface, .**
17120 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
17130 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72  p() API always r
17140 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
17150 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20   error code,.** 
17160 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
17170 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72  following any er
17180 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
17190 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
171a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
171b0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
171c0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  all [sqlite3_res
171d0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
171e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
171f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
17200 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65  d one of the spe
17210 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45  cific.** [SQLITE
17220 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20  _ERROR | result 
17230 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
17240 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
17250 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
17260 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
17270 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
17280 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
17290 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
172a0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
172b0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
172c0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
172d0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
172e0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
172f0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
17300 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
17310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
17320 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
17330 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
17340 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17350 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
17360 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
17370 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65  hen the .** more
17380 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54   specific [SQLIT
17390 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
173a0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
173b0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
173c0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
173d0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
173e0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
173f0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
17400 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
17410 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
17420 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
17430 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
17440 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
17450 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37  esult set {F1377
17460 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0}.**.** Return 
17470 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
17480 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
17490 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
174a0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
174b0 20 7b 46 31 33 37 37 31 7d 20 41 66 74 65 72 20   {F13771} After 
174c0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
174d0 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74 20  e3_step()] that 
174e0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
174f0 52 4f 57 5d 2c 0a 2a 2a 20 74 68 69 73 20 72 6f  ROW],.** this ro
17500 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65  utine.** will re
17510 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61  turn the same va
17520 6c 75 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69  lue as the [sqli
17530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
17540 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ()] function..**
17550 20 7b 46 31 33 37 37 32 7d 0a 2a 2a 20 41 66 74   {F13772}.** Aft
17560 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
17570 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
17580 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   an [SQLITE_DONE
17590 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
175a0 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54  , or.** a [SQLIT
175b0 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
175c0 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65  code], or before
175d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
175e0 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63  ] has been .** c
175f0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73 71  alled on the [sq
17600 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
17610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
17620 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
17630 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ime,.** this rou
17640 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
17650 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
17660 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
17670 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
17680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17690 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
176a0 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36  Datatypes {F1026
176b0 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 31  0}.**.** {F10261
176c0 7d 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  }Every value in 
176d0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
176e0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
176f0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
17700 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
17710 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
17720 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
17730 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
17740 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
17750 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
17760 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
17770 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
17780 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
17790 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
177a0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
177b0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
177c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
177d0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
177e0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
177f0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
17800 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
17810 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
17820 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
17830 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
17840 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
17850 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
17860 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
17870 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
17880 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
17890 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51  3_TEXT not.** SQ
178a0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
178b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
178c0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
178d0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
178e0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
178f0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
17900 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
17910 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
17920 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
17930 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
17940 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
17950 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
17960 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
17970 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
17980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17990 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20   Results Values 
179a0 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 46 31  From A Query {F1
179b0 33 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3800}.**.** Thes
179c0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
179d0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
179e0 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20  out.** a single 
179f0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
17a00 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72 6f 77  rrent result row
17a10 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e   of a query.  In
17a20 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65 20 74   every.** case t
17a30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17a40 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
17a50 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  o the .** [sqlit
17a60 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74  e3_stmt | SQL st
17a70 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
17a80 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61   being.** evalua
17a90 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
17aa0 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61  3_stmt*] that wa
17ab0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
17ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17ad0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
17ae0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
17af0 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65  s) and.** the se
17b00 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
17b10 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
17b20 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
17b30 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a  ch information .
17b40 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
17b50 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74  urned.  The left
17b60 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  -most column of 
17b70 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  the result set.*
17b80 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  * has an index o
17b90 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  f 0..**.** If th
17ba0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17bb0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
17bc0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
17bd0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
17be0 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69  .** the column i
17bf0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
17c00 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
17c10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a   is undefined. .
17c20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
17c30 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
17c40 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
17c50 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
17c60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
17c70 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
17c80 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
17c90 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
17ca0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
17cb0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
17cc0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65  nalize()] has be
17cd0 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65  en call subseque
17ce0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
17cf0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
17d00 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
17d10 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
17d20 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
17d30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
17d40 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
17d50 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
17d60 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
17d70 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
17d80 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
17d90 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
17da0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
17db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
17dc0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
17dd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17de0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
17df0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
17e00 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
17e10 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
17e20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
17e30 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
17e40 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
17e50 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a  re undefined.  .
17e60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
17e70 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
17e80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
17e90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
17ea0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
17eb0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
17ec0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
17ed0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
17ee0 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74  column.  The ret
17ef0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
17f00 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
17f10 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
17f20 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
17f30 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
17f40 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
17f50 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
17f60 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
17f70 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
17f80 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
17f90 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
17fa0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
17fb0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
17fc0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
17fd0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
17fe0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
17ff0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
18000 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
18010 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
18020 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
18030 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
18040 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
18050 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
18060 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
18070 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
18080 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
18090 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
180a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
180b0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
180c0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
180d0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
180e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a  olumn_bytes() .*
180f0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
18100 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18110 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
18120 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
18130 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
18140 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
18150 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
18160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
18170 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
18180 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
18190 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
181a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
181b0 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  tes..** If the r
181c0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
181d0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
181e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
181f0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
18200 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
18210 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
18220 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
18230 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
18240 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
18250 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
18260 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
18270 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
18280 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
18290 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
182a0 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
182b0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
182c0 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
182d0 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
182e0 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
182f0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
18300 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
18310 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
18320 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
18330 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
18340 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
18350 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
18360 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
18370 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
18380 6e 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 73 74  n zero-length st
18390 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
183a0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
183b0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a  d.  The return.*
183c0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
183d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
183e0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
183f0 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61 6e 20  ngth blob is an 
18400 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
18410 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
18420 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
18430 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
18440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
18450 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
18460 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
18470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
18480 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
18490 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
184a0 55 54 46 2d 31 36 20 69 6e 73 74 65 61 64 20 6f  UTF-16 instead o
184b0 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68  f UTF-8.  .** Th
184c0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
184d0 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  r is not include
184e0 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e  d in this count.
184f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18500 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
18510 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
18520 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
18530 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  iate.  For.** ex
18540 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
18550 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
18560 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
18570 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
18580 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
18590 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
185a0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
185b0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20  nternally to do 
185c0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a  the conversion.*
185d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  * automatically.
185e0 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20    The following 
185f0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
18600 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68  e conversions th
18610 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69 65  at.** are applie
18620 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
18630 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
18640 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
18650 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
18660 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
18670 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
18680 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
18690 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
186a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
186b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
186c0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
186d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
186e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
186f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
18700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
18710 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
18720 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
18730 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
18740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
18750 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
18760 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
18770 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
18780 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
18790 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
187a0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
187b0 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
187c0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
187d0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
187e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
187f0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
18800 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
18810 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
18820 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
18830 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
18840 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58  for INTEGER->TEX
18850 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
18860 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
18870 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
18880 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
18890 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
188a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
188b0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
188c0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
188d0 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
188e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
188f0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
18900 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
18910 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
18920 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
18930 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
18940 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
18950 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
18960 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
18970 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
18980 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
18990 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
189a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
189b0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
189c0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
189d0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
189e0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
189f0 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
18a00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
18a10 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
18a20 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
18a30 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
18a40 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
18a50 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
18a60 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
18a70 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
18a80 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
18a90 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
18aa0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
18ab0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
18ac0 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
18ad0 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
18ae0 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
18af0 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
18b00 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
18b10 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
18b20 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
18b30 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
18b40 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61  its.** on equava
18b50 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
18b60 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
18b70 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
18b80 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
18b90 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
18ba0 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
18bb0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
18bc0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
18bd0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
18be0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
18bf0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
18c00 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
18c10 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
18c20 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
18c30 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
18c40 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
18c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
18c60 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
18c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
18c80 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
18c90 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79  alidated. .** Ty
18ca0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
18cb0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
18cc0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
18cd0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
18ce0 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
18cf0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
18d00 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
18d10 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
18d20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
18d30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a  _column_text() .
18d40 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 73  **          or s
18d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
18d60 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
18d70 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
18d80 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
18d90 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62         need to b
18da0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
18db0 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  tring.</p></li>.
18dc0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54  **.** <li><p>  T
18dd0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
18de0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
18df0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
18e00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
18e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c  .**          sql
18e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
18e30 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
18e40 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
18e50 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
18e60 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54  *          to UT
18e70 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a  F-16.</p></li>.*
18e80 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  *.** <li><p>  Th
18e90 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
18ea0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
18eb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
18ec0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
18ed0 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
18ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
18ef0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
18f00 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
18f10 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
18f20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e         to UTF-8.
18f30 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  </p></li>.** </u
18f40 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73  l>.**.** Convers
18f50 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
18f60 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
18f70 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
18f80 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
18f90 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
18fa0 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
18fb0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
18fc0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
18fd0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
18fe0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
18ff0 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
19000 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
19010 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
19020 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
19030 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
19040 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
19050 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
19060 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20  e, but sometime 
19070 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
19080 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
19090 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
190a0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
190b0 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a  lidated.  .**.**
190c0 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
190d0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
190e0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
190f0 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
19100 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
19110 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
19120 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c  g ways:.**.**  <
19130 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
19140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
19150 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
19160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
19170 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
19180 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
19190 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
191a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
191b0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
191c0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
191d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
191e0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
191f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
19200 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f  16()</li>.**  </
19210 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
19220 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
19230 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
19240 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
19250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
19260 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71  blob(),.** or sq
19270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
19280 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
19290 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 20  orce the result 
192a0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
192b0 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  .** format, then
192c0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
192d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
192e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
192f0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a  _bytes16() to.**
19300 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
19310 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
19320 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74  o not mix call t
19330 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
19340 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71  _text() or.** sq
19350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
19360 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
19370 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
19380 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64  _bytes16().  And
19390 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63   do not.** mix c
193a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
193b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
193c0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
193d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
193e0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  es()..**.** The 
193f0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
19400 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
19410 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
19420 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
19430 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
19440 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
19450 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
19460 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
19470 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
19480 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
19490 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f  alled.  The memo
194a0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
194b0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
194c0 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72   and blobs is fr
194d0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
194e0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
194f0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
19500 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
19510 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
19520 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
19530 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
19540 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20  , etc. into .** 
19550 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
19560 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d  ..**.** If a mem
19570 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
19580 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
19590 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
195a0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
195b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
195c0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
195d0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
195e0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
195f0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
19600 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
19610 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
19620 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
19630 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
19640 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
19650 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
19660 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
19670 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
19680 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  NOMEM]..*/.const
19690 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
196a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
196b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
196c0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
196d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
196e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
196f0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
19700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
19710 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
19720 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
19730 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
19740 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
19750 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
19760 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
19770 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
19780 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
19790 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
197a0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
197b0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
197c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
197d0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
197e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
197f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
19800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
19810 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
19820 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
19830 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
19840 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
19850 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
19860 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
19870 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
19880 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
19890 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
198a0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
198b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
198c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
198d0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
198e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
198f0 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a  bject {F13300}.*
19900 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19910 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
19920 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
19930 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b  o delete a .** [
19940 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63  sqlite3_stmt | c
19950 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
19960 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73  ement]. If the s
19970 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
19980 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
19990 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78  fully, or not ex
199a0 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
199b0 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  hen SQLITE_OK is
199c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
199d0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
199e0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
199f0 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b  ed then an .** [
19a00 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
19a10 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 53  rror code] or [S
19a20 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
19a30 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f   | extended erro
19a40 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65  r code].** is re
19a50 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54  turned. .**.** T
19a60 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
19a70 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
19a80 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
19a90 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
19aa0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
19ab0 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 6d 61  tmt | virtual ma
19ac0 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 65 20  chine].  If the 
19ad0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
19ae0 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70  has not .** comp
19af0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
19b00 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
19b10 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
19b20 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
19b30 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
19b40 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75  or or an interru
19b50 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74  pt.  (See [sqlit
19b60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e  e3_interrupt()].
19b70 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65  ) .** Incomplete
19b80 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20   updates may be 
19b90 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20  rolled back and 
19ba0 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e  transactions can
19bb0 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70  celled,  .** dep
19bc0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
19bd0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
19be0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
19bf0 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20  _ERROR | result 
19c00 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
19c10 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
19c20 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  BORT]..*/.int sq
19c30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
19c40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
19c50 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
19c60 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
19c70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
19c80 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d   Object {F13330}
19c90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19ca0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
19cb0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
19cc0 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71   reset a .** [sq
19cd0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
19ce0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
19cf0 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  ent] object..** 
19d00 62 61 63 6b 20 74 6f 20 69 74 27 73 20 69 6e 69  back to it's ini
19d10 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
19d20 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
19d30 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
19d40 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
19d50 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
19d60 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
19d70 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
19d80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
19d90 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
19da0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
19db0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
19dc0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
19dd0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
19de0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
19df0 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73  ndings..*/.int s
19e00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
19e10 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
19e20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19e30 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
19e40 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
19e50 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a  ions {F16100}.**
19e60 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
19e70 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
19e80 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
19e90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
19ea0 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f   aggregates.** o
19eb0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
19ec0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78  e behavior of ex
19ed0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
19ee0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
19ef0 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66  es.  The.** diff
19f00 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77  erence only betw
19f10 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74  een the two is t
19f20 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70  hat the second p
19f30 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a  arameter, the.**
19f40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
19f50 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
19f60 72 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20  r aggregate, is 
19f70 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
19f80 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
19f90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
19fa0 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72  ) and UTF-16 for
19fb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
19fc0 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  function16()..**
19fd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19fe0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73  gument is the [s
19ff0 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73  qlite3 | databas
1a000 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68  e handle] that h
1a010 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20  olds the.** SQL 
1a020 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
1a030 65 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61  egate is to be a
1a040 64 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65  dded or redefine
1a050 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a  d. If a single.*
1a060 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d  * program uses m
1a070 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
1a080 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74  abase handle int
1a090 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51  ernally, then SQ
1a0a0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f  L.** functions o
1a0b0 72 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73  r aggregates mus
1a0c0 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
1a0d0 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20  idually to each 
1a0e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
1a0f0 6c 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68  le with which th
1a100 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e  ey will be used.
1a110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1a120 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1a130 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
1a140 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
1a150 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20  e created.** or 
1a160 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  redefined..** Th
1a170 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
1a180 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
1a190 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
1a1a0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a  clusive of the .
1a1b0 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ** zero-terminat
1a1c0 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
1a1d0 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
1a1e0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
1a1f0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
1a200 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
1a210 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
1a220 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
1a230 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
1a240 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53  l result in an S
1a250 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f  QLITE_ERROR erro
1a260 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  r..**.** The thi
1a270 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1a280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
1a290 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
1a2a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
1a2b0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
1a2c0 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
1a2d0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1a2e0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
1a2f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
1a300 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
1a310 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
1a320 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1a330 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
1a340 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
1a350 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
1a360 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
1a370 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
1a380 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
1a390 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
1a3a0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
1a3b0 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
1a3c0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1a3d0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
1a3e0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
1a3f0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
1a400 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
1a410 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
1a420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
1a430 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
1a440 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
1a450 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
1a460 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
1a470 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
1a480 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
1a490 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
1a4a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
1a4b0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
1a4c0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
1a4d0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
1a4e0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
1a4f0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
1a500 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
1a510 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
1a520 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
1a530 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
1a540 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
1a550 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
1a560 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
1a570 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
1a580 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
1a590 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
1a5a0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
1a5b0 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
1a5c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
1a5d0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
1a5e0 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20  re what.** text 
1a5f0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1a600 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
1a610 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
1a620 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  d be.** [SQLITE_
1a630 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
1a640 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
1a650 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
1a660 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
1a670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1a680 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
1a690 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
1a6a0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
1a6b0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1a6c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
1a6d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
1a6e0 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
1a6f0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
1a700 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
1a710 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
1a720 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
1a730 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
1a740 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
1a750 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
1a760 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
1a770 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
1a780 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
1a790 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
1a7a0 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75  on of.** the xFu
1a7b0 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  nc callback only
1a7c0 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
1a7d0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
1a7e0 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a   as the xStep.**
1a7f0 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61   and xFinal para
1a800 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
1a810 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
1a820 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
1a830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1a840 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  of xStep and xFi
1a850 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
1a860 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
1a870 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
1a880 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e  te an.** existin
1a890 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  g SQL function o
1a8a0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
1a8b0 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
1a8c0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
1a8d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
1a8e0 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64   It is permitted
1a8f0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
1a900 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
1a910 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
1a920 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
1a930 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
1a940 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
1a950 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
1a960 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
1a970 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
1a980 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74 20   perferred text 
1a990 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69  encodings.  SQLi
1a9a0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
1a9b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1a9c0 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  n most closely m
1a9d0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
1a9e0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
1a9f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
1aa00 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  sed..*/.int sqli
1aa10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1aa20 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
1aa30 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
1aa40 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
1aa50 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
1aa60 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
1aa70 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  d*,.  void (*xFu
1aa80 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
1aa90 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
1aaa0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
1aab0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
1aac0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
1aad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
1aae0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
1aaf0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
1ab00 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
1ab10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1ab20 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
1ab30 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  *,.  const void 
1ab40 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
1ab50 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
1ab60 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
1ab70 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  id*,.  void (*xF
1ab80 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
1ab90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
1aba0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
1abb0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
1abc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
1abd0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
1abe0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
1abf0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
1ac00 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
1ac10 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
1ac20 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36 30  ncodings {F10260
1ac30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1ac40 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
1ac50 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
1ac60 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
1ac70 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
1ac80 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
1ac90 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
1aca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1acb0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
1acc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1acd0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
1ace0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1acf0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
1ad00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ad10 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
1ad20 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
1ad30 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
1ad40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1ad50 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
1ad60 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
1ad70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
1ad80 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
1ad90 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
1ada0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
1adb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1adc0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
1add0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
1ade0 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73  solete Functions
1adf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
1ae00 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e  ctions are all n
1ae10 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e  ow obsolete.  In
1ae20 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
1ae30 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
1ae40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
1ae50 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77  th older code, w
1ae60 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75  e continue to su
1ae70 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66  pport.** these f
1ae80 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76  unctions.  Howev
1ae90 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d  er, new developm
1aea0 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f  ent projects sho
1aeb0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
1aec0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
1aed0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
1aee0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
1aef0 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
1af00 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
1af10 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
1af20 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
1af30 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e  ou want they do.
1af40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1af50 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
1af60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1af70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
1af80 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
1af90 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tmt*);.int sqlit
1afa0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
1afb0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
1afc0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
1afd0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
1afe0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
1aff0 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  oid);.void sqlit
1b000 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
1b010 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  p(void);.int sql
1b020 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
1b030 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
1b040 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
1b050 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
1b060 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _int64);../*.** 
1b070 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
1b080 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
1b090 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
1b0a0 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a  s {F15100}.**.**
1b0b0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
1b0c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1b0d0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
1b0e0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
1b0f0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
1b100 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
1b110 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
1b120 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
1b130 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
1b140 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
1b150 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
1b160 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
1b170 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
1b180 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
1b190 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
1b1a0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
1b1b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1b1c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1b1d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1b1e0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
1b1f0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
1b200 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
1b210 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
1b220 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
1b230 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
1b240 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
1b250 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
1b260 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
1b270 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
1b280 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
1b290 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
1b2a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
1b2b0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
1b2c0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
1b2d0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
1b2e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1b2f0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
1b300 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
1b310 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
1b320 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
1b330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
1b340 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
1b350 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
1b360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
1b370 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  umn_blob | sqlit
1b380 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74  e3_column_* rout
1b390 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68 61  ines] except tha
1b3a0 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  t .** these rout
1b3b0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
1b3c0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  le [sqlite3_valu
1b3d0 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  e*] pointer inst
1b3e0 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ead.** of an [sq
1b3f0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
1b400 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
1b410 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
1b420 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
1b430 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
1b440 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
1b450 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20 73  tracts a UTF16 s
1b460 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
1b470 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
1b480 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
1b490 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
1b4a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
1b4b0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
1b4c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
1b4d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
1b4e0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31 36  ** extract UTF16
1b4f0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
1b500 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
1b510 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
1b520 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
1b530 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
1b540 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
1b550 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1b560 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
1b570 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
1b580 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
1b590 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
1b5a0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
1b5b0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
1b5c0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
1b5d0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
1b5e0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
1b5f0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
1b600 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
1b610 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
1b620 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72  formation (in or
1b630 64 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20  der.** words if 
1b640 74 68 65 20 76 61 6c 75 65 20 69 73 20 6f 72 69  the value is ori
1b650 67 69 6e 61 6c 20 61 20 73 74 72 69 6e 67 20 74  ginal a string t
1b660 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
1b670 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
1b680 20 69 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74   it is done.  Ot
1b690 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
1b6a0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54  rsion occurs.  T
1b6b0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  he .** [SQLITE_I
1b6c0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
1b6d0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
1b6e0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
1b6f0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
1b700 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
1b710 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
1b720 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
1b730 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72  ter that.** is r
1b740 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
1b750 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
1b760 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
1b770 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
1b780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
1b790 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
1b7a0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
1b7b0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
1b7c0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
1b7d0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
1b7e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
1b7f0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
1b800 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
1b810 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
1b820 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
1b830 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  6()].  .**.** Th
1b840 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
1b850 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
1b860 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
1b870 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
1b880 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
1b890 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69 74 65  plied the sqlite
1b8a0 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d 65 74  3_value* paramet
1b8b0 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20 74  ers..** Or, if t
1b8c0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1b8d0 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65 73  * argument comes
1b8e0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1b8f0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
1b900 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2c  )].** interface,
1b910 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f 75 74   then these rout
1b920 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 20 63  ines should be c
1b930 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
1b940 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ame thread.** th
1b950 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65 33 5f  at ran [sqlite3_
1b960 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 2e  column_value()].
1b970 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
1b980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
1b990 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
1b9a0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
1b9b0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
1b9c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1b9d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
1b9e0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
1b9f0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
1ba00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
1ba10 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
1ba20 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1ba30 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
1ba40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
1ba50 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1ba60 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
1ba70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
1ba80 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
1ba90 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
1baa0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
1bab0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
1bac0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
1bad0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
1bae0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
1baf0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
1bb00 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
1bb10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
1bb20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1bb30 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
1bb40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
1bb50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
1bb60 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
1bb70 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1bb80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
1bb90 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
1bba0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
1bbb0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
1bbc0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
1bbd0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31  tion Context {F1
1bbe0 36 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6210}.**.** The 
1bbf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1bc00 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
1bc10 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
1bc20 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  is routine to al
1bc30 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75  locate.** a stru
1bc40 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e  cture for storin
1bc50 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20  g their state.  
1bc60 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1bc70 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69  his routine.** i
1bc80 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70  s called for a p
1bc90 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
1bca0 61 74 65 2c 20 61 20 6e 65 77 20 73 74 72 75 63  ate, a new struc
1bcb0 74 75 72 65 20 6f 66 20 73 69 7a 65 20 6e 42 79  ture of size nBy
1bcc0 74 65 73 0a 2a 2a 20 69 73 20 61 6c 6c 6f 63 61  tes.** is alloca
1bcd0 74 65 64 2c 20 7a 65 72 6f 65 64 2c 20 61 6e 64  ted, zeroed, and
1bce0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 6e 20 73   returned.  On s
1bcf0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bd00 28 66 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  (for the.** same
1bd10 20 61 67 67 72 65 67 61 74 65 20 69 6e 73 74 61   aggregate insta
1bd20 6e 63 65 29 20 74 68 65 20 73 61 6d 65 20 62 75  nce) the same bu
1bd30 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
1bd40 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
1bd50 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
1bd60 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
1bd70 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  e the returned b
1bd80 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
1bd90 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  ate data..**.** 
1bda0 54 68 65 20 62 75 66 66 65 72 20 61 6c 6c 6f 63  The buffer alloc
1bdb0 61 74 65 64 20 69 73 20 66 72 65 65 64 20 61 75  ated is freed au
1bdc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 53  tomatically by S
1bdd0 51 4c 69 74 65 20 77 68 61 6e 20 74 68 65 20 61  QLite whan the a
1bde0 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
1bdf0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
1be00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1be10 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
1be20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a   a copy of the .
1be30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1be40 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
1be50 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
1be60 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1be70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1be80 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  e callback routi
1be90 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
1bea0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
1beb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
1bec0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1bed0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1bee0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
1bef0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
1bf00 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
1bf10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
1bf20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
1bf30 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
1bf40 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
1bf50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
1bf60 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
1bf70 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
1bf80 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
1bf90 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a  ns {F16240}.**.*
1bfa0 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20  * The pUserData 
1bfb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1bfc0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1bfd0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
1bfe0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
1bff0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
1c000 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  ] routines.** us
1c010 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75  ed to register u
1c020 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73  ser functions is
1c030 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a   available to.**
1c040 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1c050 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ion of the funct
1c060 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63  ion using this c
1c070 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  all..**.** This 
1c080 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
1c090 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
1c0a0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
1c0b0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
1c0c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
1c0d0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
1c0e0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
1c0f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1c100 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c110 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
1c120 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31 36  iliary Data {F16
1c130 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  270}.**.** The f
1c140 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
1c150 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
1c160 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
1c170 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
1c180 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d   associate meta-
1c190 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
1c1a0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
1c1b0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
1c1c0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
1c1d0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
1c1e0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
1c1f0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
1c200 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
1c210 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
1c220 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
1c230 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
1c240 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70  ta-data may be p
1c250 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
1c260 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
1c270 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
1c280 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
1c290 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
1c2a0 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
1c2b0 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
1c2c0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
1c2d0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
1c2e0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
1c2f0 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73  .** meta-data as
1c300 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1c310 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
1c320 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
1c330 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
1c340 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
1c350 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
1c360 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
1c370 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
1c380 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
1c390 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
1c3a0 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
1c3b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
1c3c0 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
1c3d0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1c3e0 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
1c3f0 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
1c400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1c410 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1c420 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1c430 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c440 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a   the meta-data.*
1c450 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1c460 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
1c470 6e 74 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  nt value to the 
1c480 63 75 72 72 65 6e 74 20 53 51 4c 20 66 75 6e 63  current SQL func
1c490 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c 20 77 68  tion.** call, wh
1c4a0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1c4b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 49  ond parameter. I
1c4c0 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20 68  f no meta-data h
1c4d0 61 73 20 62 65 65 6e 20 73 65 74 20 66 6f 72 0a  as been set for.
1c4e0 2a 2a 20 74 68 61 74 20 76 61 6c 75 65 2c 20 74  ** that value, t
1c4f0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
1c500 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
1c510 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1c520 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
1c530 69 73 20 75 73 65 64 20 74 6f 20 61 73 73 6f 63  is used to assoc
1c540 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
1c550 69 74 68 20 61 6e 20 53 51 4c 0a 2a 2a 20 66 75  ith an SQL.** fu
1c560 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
1c570 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1c580 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
1c590 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61  r to the meta-da
1c5a0 74 61 0a 2a 2a 20 74 6f 20 62 65 20 61 73 73 6f  ta.** to be asso
1c5b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1c5c0 4e 74 68 20 75 73 65 72 20 66 75 6e 63 74 69 6f  Nth user functio
1c5d0 6e 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  n argument value
1c5e0 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20  . The fourth.** 
1c5f0 70 61 72 61 6d 65 74 65 72 20 73 70 65 63 69 66  parameter specif
1c600 69 65 73 20 61 20 64 65 73 74 72 75 63 74 6f 72  ies a destructor
1c610 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 63 61   that will be ca
1c620 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d 65 74 61  lled on the meta
1c630 2d 0a 2a 2a 20 64 61 74 61 20 70 6f 69 6e 74 65  -.** data pointe
1c640 72 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 20  r to release it 
1c650 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1c660 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 20 49  nger required. I
1c670 66 20 74 68 65 20 0a 2a 2a 20 64 65 73 74 72 75  f the .** destru
1c680 63 74 6f 72 20 69 73 20 4e 55 4c 4c 2c 20 69 74  ctor is NULL, it
1c690 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 2e   is not invoked.
1c6a0 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
1c6b0 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73  ce, meta-data is
1c6c0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
1c6d0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
1c6e0 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
1c6f0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
1c700 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
1c710 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
1c720 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
1c730 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
1c740 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
1c750 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c760 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
1c770 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
1c780 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
1c790 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1c7a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
1c7b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
1c7c0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
1c7d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
1c7e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
1c7f0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
1c800 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
1c810 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
1c820 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
1c830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1c840 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
1c850 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
1c860 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30  or Behavior {F10
1c870 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  280}.**.** These
1c880 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
1c890 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  ue for the destr
1c8a0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
1c8b0 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
1c8c0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
1c8d0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
1c8e0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
1c8f0 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
1c900 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
1c910 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
1c920 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
1c930 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
1c940 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
1c950 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
1c960 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
1c970 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
1c980 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
1c990 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20  royed.  The .** 
1c9a0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1c9b0 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
1c9c0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
1c9d0 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
1c9e0 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
1c9f0 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
1ca00 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
1ca10 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
1ca20 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
1ca30 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
1ca40 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
1ca50 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
1ca60 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
1ca70 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
1ca80 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
1ca90 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
1caa0 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
1cab0 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
1cac0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
1cad0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
1cae0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
1caf0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
1cb00 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
1cb10 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
1cb20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
1cb30 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
1cb40 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
1cb50 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
1cb60 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
1cb70 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
1cb80 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46   SQL Function {F
1cb90 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16400}.**.** The
1cba0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1cbb0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
1cbc0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
1cbd0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
1cbe0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
1cbf0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
1cc00 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
1cc10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1cc20 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
1cc30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1cc40 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
1cc50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
1cc60 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1cc70 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1cc80 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
1cc90 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71  like the .** [sq
1cca0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1ccb0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
1ccc0 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  ] family of func
1ccd0 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f  tions used.** to
1cce0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
1ccf0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1cd00 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
1cd10 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
1cd20 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   to the.** [sqli
1cd30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
1cd40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64  sqlite3_bind_* d
1cd50 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1cd60 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
1cd70 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1cd80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
1cd90 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
1cda0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1cdb0 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
1cdc0 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
1cdd0 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
1cde0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
1cdf0 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
1ce00 2e 20 20 54 68 65 0a 2a 2a 20 70 61 72 61 6d 65  .  The.** parame
1ce10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ce20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
1ce30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1ce40 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 69 73 20  error16().** is 
1ce50 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
1ce60 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1ce70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ce80 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
1ce90 63 61 75 73 65 20 74 68 65 20 66 75 6e 63 74 69  cause the functi
1cea0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
1ceb0 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e  n.** to throw an
1cec0 64 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  d error indicati
1ced0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
1cee0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c   or BLOB is to l
1cef0 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73  ong.** to repres
1cf00 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ent..**.** These
1cf10 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1cf20 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
1cf30 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 68  thin the same th
1cf40 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
1cf50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  QL function asso
1cf60 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1cf70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1cf80 5d 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 76 6f  ] pointer..*/.vo
1cf90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1cfa0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
1cfb0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
1cfc0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
1cfd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
1cfe0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1cff0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
1d000 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
1d010 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1d020 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
1d030 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
1d040 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
1d050 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1d060 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
1d070 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1d080 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
1d090 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1d0a0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
1d0b0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
1d0c0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
1d0d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
1d0e0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
1d0f0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1d100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
1d110 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1d120 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1d130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
1d140 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
1d150 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
1d160 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
1d170 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
1d180 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
1d190 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1d1a0 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
1d1b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1d1c0 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
1d1d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1d1e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1d1f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
1d200 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1d210 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1d220 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1d230 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1d240 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
1d250 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
1d260 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
1d270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1d280 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1d290 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
1d2a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
1d2b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1d2c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1d2d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1d2e0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
1d2f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
1d300 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
1d310 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1d320 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
1d330 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
1d340 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1d350 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
1d360 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
1d370 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a  nces {F16600}.**
1d380 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
1d390 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
1d3a0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
1d3b0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
1d3c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d  he.** [sqlite3*]
1d3d0 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65   handle specifie
1d3e0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
1d3f0 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20  rgument. .**.** 
1d400 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
1d410 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
1d420 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
1d430 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
1d440 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
1d450 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1d460 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
1d470 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1d480 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
1d490 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
1d4a0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
1d4b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
1d4c0 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  ).  In all cases
1d4d0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
1d4e0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
1d4f0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
1d500 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
1d510 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1d520 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
1d530 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
1d540 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
1d550 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
1d560 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
1d570 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
1d580 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
1d590 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
1d5a0 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
1d5b0 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
1d5c0 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
1d5d0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
1d5e0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
1d5f0 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
1d600 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
1d610 70 65 63 74 69 76 65 6c 79 2e 20 20 54 68 65 0a  pectively.  The.
1d620 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
1d630 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
1d640 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
1d650 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61  IGNED] to indica
1d660 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72  te that.** the r
1d670 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70  outine expects p
1d680 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69  ointers to 16-bi
1d690 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73  t word aligned s
1d6a0 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46  trings.** of UTF
1d6b0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1d6c0 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74   byte order of t
1d6d0 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
1d6e0 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
1d6f0 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
1d700 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
1d710 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
1d720 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
1d730 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 69 73  gument. If it is
1d740 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
1d750 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
1d760 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
1d770 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
1d780 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
1d790 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
1d7a0 6d 6f 72 65 29 2e 20 45 61 63 68 20 74 69 6d 65  more). Each time
1d7b0 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 73 75 70   the user.** sup
1d7c0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
1d7d0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
1d7e0 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
1d7f0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73  f the void* pass
1d800 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75  ed as.** the fou
1d810 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1d820 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1d830 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a  ollation() or.**
1d840 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1d850 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73  collation16() as
1d860 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
1d870 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
1d880 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
1d890 6e 74 73 20 74 6f 20 74 68 65 20 75 73 65 72 2d  nts to the user-
1d8a0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
1d8b0 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73   are two strings
1d8c0 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73  ,.** each repres
1d8d0 65 6e 74 65 64 20 62 79 20 61 20 5b 6c 65 6e 67  ented by a [leng
1d8e0 74 68 2c 20 64 61 74 61 5d 20 70 61 69 72 20 61  th, data] pair a
1d8f0 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68  nd encoded in th
1d900 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68  e encoding.** th
1d910 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73  at was passed as
1d920 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1d930 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  ent when the col
1d940 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
1d950 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  was.** registere
1d960 64 2e 20 54 68 65 20 75 73 65 72 20 72 6f 75 74  d. The user rout
1d970 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ine should retur
1d980 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
1d990 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a   or positive if.
1d9a0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72  ** the first str
1d9b0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
1d9c0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
1d9d0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
1d9e0 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67  second.** string
1d9f0 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
1da00 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
1da10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
1da20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1da30 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
1da40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1da50 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
1da60 61 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  apt that it take
1da70 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
1da80 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
1da90 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
1daa0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
1dab0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
1dac0 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  is called when t
1dad0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a  he collation is.
1dae0 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ** destroyed and
1daf0 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
1db00 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  y of the fourth 
1db10 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20  parameter void* 
1db20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68  pointer.** of th
1db30 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
1db40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e  _collation_v2().
1db50 20 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65    Collations are
1db60 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a   destroyed when.
1db70 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  ** they are over
1db80 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20  ridden by later 
1db90 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
1dba0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
1dbb0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20  functions.** or 
1dbc0 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  when the [sqlite
1dbd0 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
1dbe0 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73  dle is closed us
1dbf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
1dc00 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  se()]..**.** The
1dc10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1dc20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 69  collation_v2() i
1dc30 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
1dc40 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20  rimental and.** 
1dc50 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1dc60 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
1dc70 61 73 65 73 2e 20 20 54 68 65 20 6f 74 68 65 72  ases.  The other
1dc80 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
1dc90 69 6f 6e 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ion.** functions
1dca0 20 61 72 65 20 73 74 61 62 6c 65 2e 0a 2a 2f 0a   are stable..*/.
1dcb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
1dcc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
1dcd0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
1dce0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
1dcf0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
1dd00 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
1dd10 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
1dd20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1dd30 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1dd40 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
1dd50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1dd60 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
1dd70 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
1dd80 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
1dd90 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
1dda0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
1ddb0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
1ddc0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
1ddd0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
1dde0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
1ddf0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
1de00 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1de10 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
1de20 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
1de30 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
1de40 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
1de50 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
1de60 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
1de70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
1de80 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
1de90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dea0 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
1deb0 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  ed Callbacks {F1
1dec0 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  6700}.**.** To a
1ded0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
1dee0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
1def0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1df00 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
1df10 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
1df20 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
1df30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
1df40 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
1df50 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ith the.** datab
1df60 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65  ase handle to be
1df70 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
1df80 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
1df90 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1dfa0 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e   is.** required.
1dfb0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
1dfc0 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
1dfd0 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
1dfe0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1dff0 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
1e000 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
1e010 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
1e020 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
1e030 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
1e040 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
1e050 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 49  oded in UTF-8. I
1e060 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
1e070 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
1e080 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65  s used, the name
1e090 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  s.** are passed 
1e0a0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
1e0b0 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
1e0c0 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74   order. A call t
1e0d0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63  o either.** func
1e0e0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
1e0f0 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
1e100 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ack..**.** When 
1e110 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1e120 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
1e130 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
1e140 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
1e150 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
1e160 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1e170 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
1e180 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
1e190 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1e1a0 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65 63  ded16(). The sec
1e1b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1e1c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1e1d0 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 72  handle. The thir
1e1e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
1e1f0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
1e200 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
1e210 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  6BE], or.** [SQL
1e220 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
1e230 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
1e240 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
1e250 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
1e260 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
1e270 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
1e280 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
1e290 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
1e2a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
1e2b0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
1e2c0 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  equence..**.** T
1e2d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1e2e0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
1e2f0 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
1e300 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
1e310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1e320 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
1e330 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1e340 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
1e350 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
1e360 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1e370 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
1e380 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1e390 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
1e3a0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
1e3b0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
1e3c0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
1e3d0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
1e3e0 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
1e3f0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1e400 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
1e410 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
1e420 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
1e430 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
1e440 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
1e450 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
1e460 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
1e470 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
1e480 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
1e490 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
1e4a0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
1e4b0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
1e4c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
1e4d0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
1e4e0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
1e4f0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
1e500 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
1e510 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
1e520 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
1e530 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1e540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e550 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
1e560 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
1e570 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
1e580 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
1e590 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
1e5a0 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
1e5b0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
1e5c0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
1e5d0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
1e5e0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
1e5f0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
1e600 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
1e610 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
1e620 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
1e630 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1e640 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
1e650 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
1e660 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
1e670 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
1e680 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
1e690 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
1e6a0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1e6b0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
1e6c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1e6e0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
1e6f0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
1e700 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
1e710 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
1e720 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
1e730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e740 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63  F:  Suspend Exec
1e750 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
1e760 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a  t Time {F10530}.
1e770 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1e780 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
1e790 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
1e7a0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
1e7b0 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
1e7c0 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
1e7d0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
1e7e0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
1e7f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
1e800 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1e810 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
1e820 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
1e830 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d  uests with .** m
1e840 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
1e850 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
1e860 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
1e870 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20  e rounded up to 
1e880 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
1e890 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
1e8a0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
1e8b0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
1e8c0 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74  ally .** request
1e8d0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
1e8e0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
1e8f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1e900 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
1e910 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
1e920 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
1e930 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
1e940 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1e950 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1e960 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
1e970 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
1e980 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e990 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65  EF:  Name Of The
1e9a0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
1e9b0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20  Temporary Files 
1e9c0 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49  {F10310}.**.** I
1e9d0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
1e9e0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
1e9f0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
1ea00 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
1ea10 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
1ea20 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65  lder (a.ka. dire
1ea30 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
1ea40 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
1ea50 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
1ea60 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c  QLite will be pl
1ea70 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
1ea80 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73  ectory.  If this
1ea90 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
1eaa0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
1eab0 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61  en SQLite does a
1eac0 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
1ead0 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f  ppropriate tempo
1eae0 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72  rary.** file dir
1eaf0 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
1eb00 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1eb10 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
1eb20 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61  able once a data
1eb30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1eb40 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e  ** has been open
1eb50 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e  ed.  It is inten
1eb60 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
1eb70 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
1eb80 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
1eb90 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
1eba0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
1ebb0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
1ebc0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
1ebd0 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
1ebe0 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e  ll and remain un
1ebf0 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74  changed thereaft
1ec00 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  er..*/.SQLITE_EX
1ec10 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
1ec20 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
1ec30 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
1ec40 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65  EF:  Test To See
1ec50 20 49 66 20 54 68 65 20 44 61 74 61 62 61 73 65   If The Database
1ec60 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d   Is In Auto-Comm
1ec70 69 74 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d  it Mode {F12930}
1ec80 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73  .**.** Test to s
1ec90 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ee whether or no
1eca0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  t the database c
1ecb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
1ecc0 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f  autocommit.** mo
1ecd0 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45  de.  Return TRUE
1ece0 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41   if it is and FA
1ecf0 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74  LSE if not.  Aut
1ed00 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
1ed10 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  on.** by default
1ed20 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73  .  Autocommit is
1ed30 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42   disabled by a B
1ed40 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61  EGIN statement a
1ed50 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20  nd reenabled.** 
1ed60 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d  by the next COMM
1ed70 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a  IT or ROLLBACK..
1ed80 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
1ed90 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
1eda0 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
1edb0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
1edc0 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
1edd0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28  * transactions (
1ede0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
1edf0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
1ee00 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20  [SQLITE_IOERR], 
1ee10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
1ee20 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
1ee30 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
1ee40 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
1ee50 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
1ee60 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
1ee70 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
1ee80 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
1ee90 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
1eea0 6f 75 74 20 69 66 20 53 51 4c 69 74 65 20 61 75  out if SQLite au
1eeb0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
1eec0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
1eed0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
1eee0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
1eef0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
1ef00 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
1ef10 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
1ef20 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
1ef30 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
1ef40 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
1ef50 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
1ef60 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
1ef70 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
1ef80 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
1ef90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
1efa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1efb0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
1efc0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1efd0 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65  I3REF:  Find The
1efe0 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
1eff0 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
1f000 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30  tatement {F13120
1f010 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
1f020 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
1f030 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f  tabase handle to
1f040 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73 71 6c   which a.** [sql
1f050 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
1f060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f070 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 69 73  belongs..** This
1f080 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74   is the same dat
1f090 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61  abase handle tha
1f0a0 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72  t was.** the fir
1f0b0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1f0c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1f0d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1f0e0 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61   variants.** tha
1f0f0 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72  t was used to cr
1f100 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
1f110 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
1f120 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
1f130 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
1f140 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
1f150 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t*);.../*.** CAP
1f160 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
1f170 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
1f180 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
1f190 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a  s {F12950}.**.**
1f1a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   These routines.
1f1b0 2a 2a 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  ** register call
1f1c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1f1d0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
1f1e0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
1f1f0 69 6f 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74  ion.** is commit
1f200 74 65 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61  ted or rolled ba
1f210 63 6b 2e 20 20 54 68 65 20 70 41 72 67 20 61 72  ck.  The pArg ar
1f220 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
1f230 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74   through.** to t
1f240 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
1f250 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
1f260 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
1f270 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75  unction .** retu
1f280 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1f290 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
1f2a0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
1f2b0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
1f2c0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
1f2d0 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
1f2e0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
1f2f0 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 20   its pArg value 
1f300 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
1f310 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
1f320 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1f330 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20  * Registering a 
1f340 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
1f350 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
1f360 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ack..**.** For t
1f370 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1f380 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
1f390 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
1f3a0 6f 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20  o have been .** 
1f3b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
1f3c0 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
1f3d0 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
1f3e0 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
1f3f0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
1f400 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
1f410 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
1f420 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20  lback to occur. 
1f430 54 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  The .** callback
1f440 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
1f450 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
1f460 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
1f470 79 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b  y rolled.** back
1f480 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
1f490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f4a0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1f4b0 2a 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65  * These are expe
1f4c0 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
1f4d0 63 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a  ces and are subj
1f4e0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a  ect to change..*
1f4f0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1f500 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
1f510 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1f520 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
1f530 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
1f540 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
1f550 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
1f560 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
1f570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
1f580 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
1f590 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
1f5a0 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 52  {F12970}.**.** R
1f5b0 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61  egister a callba
1f5c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ck function with
1f5d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1f5e0 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66  nnection identif
1f5f0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1f600 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1f610 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
1f620 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
1f630 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
1f640 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
1f650 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
1f660 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
1f670 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
1f680 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ion for the same
1f690 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f   .** database co
1f6a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
1f6b0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ridden..**.** Th
1f6c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1f6d0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
1f6e0 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
1f6f0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20  o invoke when a 
1f700 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
1f710 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
1f720 64 65 6c 65 74 65 64 2e 20 54 68 65 20 66 69 72  deleted. The fir
1f730 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1f740 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a  he callback is.*
1f750 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  * a copy of the 
1f760 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1f770 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
1f780 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73 65 63  _hook(). The sec
1f790 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ond callback .**
1f7a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
1f7b0 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 52   of SQLITE_INSER
1f7c0 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  T, SQLITE_DELETE
1f7d0 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 54   or SQLITE_UPDAT
1f7e0 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  E, depending.** 
1f7f0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
1f800 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
1f810 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
1f820 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 69  invoked. The thi
1f830 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74  rd and .** fourt
1f840 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
1f850 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
1f860 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
1f870 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1f880 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20   .** table name 
1f890 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
1f8a0 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 65  ffected row. The
1f8b0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
1f8c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a  parameter is .**
1f8d0 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
1f8e0 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61  e row. In the ca
1f8f0 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
1f900 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77   this is the row
1f910 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65  id after .** the
1f920 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
1f930 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
1f940 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
1f950 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
1f960 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
1f970 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
1f980 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
1f990 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
1f9a0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
1f9b0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
1f9c0 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
1f9d0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
1f9e0 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
1f9f0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
1fa00 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55  .** Otherwise NU
1fa10 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
1fa20 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1fa30 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
1fa40 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
1fa50 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
1fa60 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
1fa70 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
1fa80 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
1fa90 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
1faa0 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
1fab0 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
1fac0 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 46 31   Pager Cache {F1
1fad0 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0330}.**.** This
1fae0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1faf0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1fb00 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20   sharing of the 
1fb10 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a  database cache.*
1fb20 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74  * and schema dat
1fb30 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74  a structures bet
1fb40 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  ween connections
1fb50 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
1fb60 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e  abase..** Sharin
1fb70 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
1fb80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
1fb90 74 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65  true and disable
1fba0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
1fbb0 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a  t.** is false..*
1fbc0 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 69  *.** Beginning i
1fbd0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1fbe0 20 33 2e 35 2e 30 2c 20 63 61 63 68 65 20 73 68   3.5.0, cache sh
1fbf0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
1fc00 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a   and disabled.**
1fc10 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
1fc20 72 6f 63 65 73 73 2e 20 20 49 6e 20 70 72 69 6f  rocess.  In prio
1fc30 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
1fc40 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61  Lite, sharing wa
1fc50 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20  s.** enabled or 
1fc60 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
1fc70 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
1fc80 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ely..**.** The c
1fc90 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
1fca0 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
1fcb0 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
1fcc0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
1fcd0 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
1fce0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1fcf0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1fd00 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
1fd10 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
1fd20 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
1fd30 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
1fd40 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
1fd50 69 6e 67 20 6d 6f 64 65 20 74 68 61 74 20 77 61  ing mode that wa
1fd60 73 0a 2a 2a 20 69 6e 20 65 66 66 65 63 74 20 61  s.** in effect a
1fd70 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
1fd80 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  were opened..**.
1fd90 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
1fda0 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
1fdb0 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
1fdc0 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72  ache.  When shar
1fdd0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1fde0 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
1fdf0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
1fe00 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74  le()] API used t
1fe10 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
1fe20 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
1fe30 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
1fe40 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
1fe50 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1fe60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1fe70 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
1fe80 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20   was.** enabled 
1fe90 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63  or disabled succ
1fea0 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 53  essfully.  An [S
1feb0 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72  QLITE_ERROR | er
1fec0 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
1fed0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
1fee0 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64  se..**.** Shared
1fef0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
1ff00 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ed by default.  
1ff10 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
1ff20 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
1ff30 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1ff40 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
1ff50 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
1ff60 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
1ff70 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
1ff80 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
1ff90 63 69 74 6c 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  citly..*/.int sq
1ffa0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1ffb0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
1ffc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ffd0 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65    Attempt To Fre
1ffe0 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46  e Heap Memory {F
1fff0 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 74 74  17340}.**.** Att
20000 65 6d 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62  empt to free N b
20010 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d  ytes of heap mem
20020 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
20030 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
20040 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  l.** memory allo
20050 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20  cations held by 
20060 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
20070 72 61 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d  rary (example: m
20080 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74  emory .** used t
20090 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
200a0 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
200b0 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a  e performance)..
200c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
200d0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
200e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
200f0 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c  REF:  Impose A L
20100 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
20110 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a  e {F17350}.**.**
20120 20 50 6c 61 63 65 20 61 20 22 73 6f 66 74 22 20   Place a "soft" 
20130 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
20140 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
20150 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
20160 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53  llocated.** by S
20170 51 4c 69 74 65 2e 20 20 49 66 20 61 6e 20 69 6e  QLite.  If an in
20180 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f  ternal allocatio
20190 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a  n is requested .
201a0 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78  ** that would ex
201b0 63 65 65 64 20 74 68 65 20 73 70 65 63 69 66 69  ceed the specifi
201c0 65 64 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ed limit, [sqlit
201d0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
201e0 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  y()] is.** invok
201f0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
20200 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
20210 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
20220 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
20230 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a  .** is made..**.
20240 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  ** The limit is 
20250 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62  called "soft", b
20260 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74  ecause if [sqlit
20270 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
20280 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66  y()] cannot.** f
20290 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d  ree sufficient m
202a0 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74  emory to prevent
202b0 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20   the limit from 
202c0 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a  being exceeded,.
202d0 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73  ** the memory is
202e0 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61   allocated anywa
202f0 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e  y and the curren
20300 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  t operation proc
20310 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65  eeds..**.** A ne
20320 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
20330 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73  alue for N means
20340 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
20350 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  o soft heap limi
20360 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  t and.** [sqlite
20370 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
20380 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
20390 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d   called when mem
203a0 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64  ory is exhausted
203b0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
203c0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73   value for the s
203d0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
203e0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51  s zero..**.** SQ
203f0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
20400 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
20410 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
20420 6c 69 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69  limit.  But if i
20430 74 0a 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74  t.** is unable t
20440 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20  o reduce memory 
20450 75 73 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20  usage below the 
20460 73 6f 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63  soft limit, exec
20470 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f  ution will.** co
20480 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65  ntinue without e
20490 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61  rror or notifica
204a0 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77  tion.  This is w
204b0 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  hy the limit is 
204c0 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f  .** called a "so
204d0 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69  ft" limit.  It i
204e0 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
204f0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
20500 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
20510 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69  .5.0, this routi
20520 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69  ne only constrai
20530 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ned the memory.*
20540 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61  * allocated by a
20550 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d   single thread -
20560 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
20570 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72   in which this r
20580 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20  outine.** runs. 
20590 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
205a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
205b0 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68  .5.0, the soft h
205c0 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20  eap limit is.** 
205d0 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74  applied to all t
205e0 68 72 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c  hreads.  The val
205f0 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
20600 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
20610 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
20620 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
20630 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
20640 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
20650 20 74 68 72 65 61 64 73 2e 20 20 49 6e 0a 2a 2a   threads.  In.**
20660 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74   version 3.5.0 t
20670 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61  here is no mecha
20680 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e  nism for limitin
20690 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65  g the heap usage
206a0 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75   for.** individu
206b0 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  al threads..*/.v
206c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
206d0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
206e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
206f0 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61  F:  Extract Meta
20700 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
20710 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b  umn Of A Table {
20720 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12850}.**.** Th
20730 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
20740 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20  turns meta-data 
20750 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
20760 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
20770 63 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a  cific database.*
20780 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  * table accessib
20790 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e  le using the con
207a0 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70  nection handle p
207b0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
207c0 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20  st function .** 
207d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
207e0 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64  The column is id
207f0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
20800 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e  second, third an
20810 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
20820 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20  ers to .** this 
20830 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65  function. The se
20840 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
20850 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
20860 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
20870 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
20880 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20  ", "temp" or an 
20890 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
208a0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
208b0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
208c0 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66  able or NULL. If
208d0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
208e0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
208f0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
20900 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
20910 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
20920 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
20930 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
20940 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a  engine uses to .
20950 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
20960 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
20970 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  erences..**.** T
20980 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
20990 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
209a0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
209b0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
209c0 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d  d column .** nam
209d0 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
209e0 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
209f0 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
20a00 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
20a10 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  rs .** may be NU
20a20 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69  LL..**.** Meta i
20a30 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
20a40 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
20a50 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
20a60 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
20a70 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61   as.** the 5th a
20a80 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
20a90 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
20aa0 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f   function. Any o
20ab0 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75  f these .** argu
20ac0 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c  ments may be NUL
20ad0 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
20ae0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
20af0 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
20b00 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ta .** informati
20b10 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a  on is ommitted..
20b20 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50  **.** <pre>.** P
20b30 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74  arameter     Out
20b40 70 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65  put Type      De
20b50 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d  scription.** ---
20b60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
20b70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
20b80 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20  .**.**   5th    
20b90 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a       const char*
20ba0 20 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a        Data type.
20bb0 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20  **   6th        
20bc0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20   const char*    
20bd0 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65    Name of the de
20be0 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
20bf0 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37  sequence .**   7
20c00 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
20c10 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
20c20 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68   if the column h
20c30 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  as a NOT NULL co
20c40 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74  nstraint.**   8t
20c50 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
20c60 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
20c70 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  if the column is
20c80 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49   part of the PRI
20c90 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74  MARY KEY.**   9t
20ca0 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
20cb0 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
20cc0 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  if the column is
20cd0 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a   AUTOINCREMENT.*
20ce0 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a  * </pre>.**.**.*
20cf0 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69  * The memory poi
20d00 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
20d10 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
20d20 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
20d30 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69  he .** declarati
20d40 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c  on type and coll
20d50 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
20d60 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74  s valid only unt
20d70 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20  il the next .** 
20d80 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69  call to any sqli
20d90 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
20da0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
20db0 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73  ecified table is
20dc0 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77   actually a view
20dd0 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  , then an error 
20de0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
20df0 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
20e00 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
20e10 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
20e20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
20e30 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49   .** INTEGER PRI
20e40 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20  MARY KEY column 
20e50 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
20e60 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
20e70 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a  en the output .*
20e80 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
20e90 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
20ea0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
20eb0 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72   column. If ther
20ec0 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
20ed0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49  citly declared I
20ee0 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20  PK column, then 
20ef0 74 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d  the output param
20f00 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
20f10 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a   .** follows:.**
20f20 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
20f30 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
20f40 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
20f50 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
20f60 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
20f70 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
20f80 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
20f90 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
20fa0 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
20fb0 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  /pre>.**.** This
20fc0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
20fd0 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
20fe0 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
20ff0 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
21000 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
21010 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
21020 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
21030 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
21040 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
21050 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
21060 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63  n SQLITE error c
21070 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
21080 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
21090 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20  sage.** left in 
210a0 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  the database han
210b0 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69  dle (to be retri
210c0 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  eved using sqlit
210d0 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a  e3_errmsg())..**
210e0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20  .** This API is 
210f0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
21100 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
21110 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
21120 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  the.** SQLITE_EN
21130 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
21140 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f  DATA preprocesso
21150 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
21160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21170 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65  _table_column_me
21180 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65  tadata(.  sqlite
21190 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
211a0 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74        /* Connect
211b0 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ion handle */.  
211c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
211d0 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44  ame,        /* D
211e0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20  atabase name or 
211f0 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  NULL */.  const 
21200 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65  char *zTableName
21210 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e  ,     /* Table n
21220 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ame */.  const c
21230 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65  har *zColumnName
21240 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e  ,    /* Column n
21250 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ame */.  char co
21260 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65  nst **pzDataType
21270 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20  ,    /* OUTPUT: 
21280 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79  Declared data ty
21290 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  pe */.  char con
212a0 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20  st **pzCollSeq, 
212b0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43      /* OUTPUT: C
212c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
212d0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20  e name */.  int 
212e0 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20  *pNotNull,      
212f0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
21300 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e  T: True if NOT N
21310 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65  ULL constraint e
21320 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a  xists */.  int *
21330 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20  pPrimaryKey,    
21340 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
21350 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
21360 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20   part of PK */. 
21370 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20   int *pAutoinc  
21380 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
21390 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
213a0 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69  column is auto-i
213b0 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a  ncrement */.);..
213c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
213d0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
213e0 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a  n {F12600}.**.**
213f0 20 41 74 74 65 6d 70 74 20 74 6f 20 6c 6f 61 64   Attempt to load
21400 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
21410 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e  sion library con
21420 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69  tained in the fi
21430 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 20 54 68  le.** zFile.  Th
21440 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
21450 20 7a 50 72 6f 63 2e 20 20 7a 50 72 6f 63 20 6d   zProc.  zProc m
21460 61 79 20 62 65 20 30 20 69 6e 20 77 68 69 63 68  ay be 0 in which
21470 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 6e 61 6d   case the.** nam
21480 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
21490 6f 69 6e 74 20 64 65 66 61 75 6c 74 73 20 74 6f  oint defaults to
214a0 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
214b0 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a  ion_init"..**.**
214c0 20 52 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   Return [SQLITE_
214d0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
214e0 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  nd [SQLITE_ERROR
214f0 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67  ] if something g
21500 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a  oes wrong..**.**
21510 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   If an error occ
21520 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67  urs and pzErrMsg
21530 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20   is not 0, then 
21540 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77  fill *pzErrMsg w
21550 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65  ith .** error me
21560 73 73 61 67 65 20 74 65 78 74 2e 20 20 54 68 65  ssage text.  The
21570 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
21580 6e 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68  n should free th
21590 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20  is memory.** by 
215a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
215b0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
215c0 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
215d0 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
215e0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
215f0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
21600 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69  ension()].** pri
21610 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
21620 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72  is API or an err
21630 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
21640 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
21650 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
21660 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
21670 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c  b,          /* L
21680 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f  oad the extensio
21690 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61  n into this data
216a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
216b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
216c0 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61  *zFile,    /* Na
216d0 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  me of the shared
216e0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
216f0 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f  ing extension */
21700 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
21710 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72  Proc,    /* Entr
21720 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65  y point.  Derive
21730 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20  d from zFile if 
21740 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  0 */.  char **pz
21750 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20  ErrMsg       /* 
21760 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67  Put error messag
21770 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20  e here if not 0 
21780 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
21790 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
217a0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
217b0 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32  ion Loading {F12
217c0 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  620}.**.** So as
217d0 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
217e0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
217f0 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
21800 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
21810 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
21820 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
21830 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
21840 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
21850 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
21860 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
21870 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
21880 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
21890 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
218a0 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
218b0 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
218c0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
218d0 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
218e0 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49  n and.** off.  I
218f0 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  t is off by defa
21900 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ult.  See ticket
21910 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61   #1863..**.** Ca
21920 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
21930 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f  with onoff==1 to
21940 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
21950 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e  loading on.** an
21960 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
21970 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20  noff==0 to turn 
21980 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
21990 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
219a0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
219b0 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
219c0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
219d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
219e0 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65  : Make Arrangeme
219f0 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63  nts To Automatic
21a00 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
21a10 65 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a  ension {F12640}.
21a20 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61  **.** Register a
21a30 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  n extension entr
21a40 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 20  y point that is 
21a50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
21a60 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65  voked.** wheneve
21a70 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
21a80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
21a90 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  pened using.** [
21aa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
21ab0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
21ac0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
21ad0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  _open_v2()]..**.
21ae0 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20  ** This API can 
21af0 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72  be invoked at pr
21b00 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e  ogram startup in
21b10 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74   order to regist
21b20 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
21b30 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e  e statically lin
21b40 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74  ked extensions t
21b50 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69  hat will be avai
21b60 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20  lable.** to all 
21b70 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
21b80 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
21b90 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
21ba0 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
21bb0 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
21bc0 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70  s routine multip
21bd0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
21be0 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
21bf0 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
21c00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
21c10 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69  ine stores a poi
21c20 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65  nter to the exte
21c30 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61  nsion in an arra
21c40 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62 74  y.** that is obt
21c50 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f  ained from mallo
21c60 63 28 29 2e 20 20 49 66 20 79 6f 75 20 72 75 6e  c().  If you run
21c70 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a   a memory leak.*
21c80 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75  * checker on you
21c90 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74  r program and it
21ca0 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20   reports a leak 
21cb0 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a  because of this.
21cc0 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69  ** array, then i
21cd0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72  nvoke [sqlite3_r
21ce0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
21cf0 69 6f 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20  ion()] prior.** 
21d00 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66  to shutdown to f
21d10 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a  ree the memory..
21d20 2a 2a 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63 20  **.** Automatic 
21d30 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79  extensions apply
21d40 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65   across all thre
21d50 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ads..**.** This 
21d60 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
21d70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
21d80 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
21d90 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c  ge or.** removal
21da0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
21db0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
21dc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
21dd0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
21de0 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b  d *xEntryPoint);
21df0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
21e00 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
21e10 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
21e20 64 69 6e 67 20 7b 46 31 32 36 36 30 7d 0a 2a 2a  ding {F12660}.**
21e30 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20  .** Disable all 
21e40 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
21e50 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20  tered automatic 
21e60 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69  extensions.  Thi
21e70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  s.** routine und
21e80 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
21e90 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c  f all prior [sql
21ea0 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65  ite3_automatic_e
21eb0 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63  xtension()].** c
21ec0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  alls..**.** This
21ed0 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61   call disabled a
21ee0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
21ef0 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61  ons in all threa
21f00 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ds..**.** This i
21f10 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
21f20 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
21f30 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
21f40 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
21f50 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
21f60 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
21f70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
21f80 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
21f90 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a  on(void);.../*.*
21fa0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
21fb0 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
21fc0 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
21fd0 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
21fe0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
21ff0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
22000 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
22010 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
22020 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
22030 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
22040 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
22050 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
22060 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
22070 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
22080 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
22090 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
220a0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
220b0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
220c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
220d0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
220e0 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65  chanism stablize
220f0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
22100 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
22110 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
22120 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
22130 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
22140 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
22150 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
22160 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
22170 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
22180 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
22190 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
221a0 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
221b0 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
221c0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
221d0 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
221e0 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
221f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
22200 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
22210 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
22220 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
22230 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
22240 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
22250 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69  /*.** A module i
22260 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72  s a class of vir
22270 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61  tual tables.  Ea
22280 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66  ch module is def
22290 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e  ined.** by an in
222a0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f  stance of the fo
222b0 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
222c0 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75  e.  This structu
222d0 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d  re consists.** m
222e0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
222f0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
22300 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
22310 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
22320 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
22330 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
22340 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
22350 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
22360 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
22370 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
22380 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
22390 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
223a0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
223b0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
223c0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
223d0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
223e0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
223f0 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
22400 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
22410 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
22420 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
22430 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
22440 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
22450 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
22460 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
22470 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
22480 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
22490 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
224a0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
224b0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
224c0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
224d0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
224e0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
224f0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
22500 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
22510 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
22520 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
22530 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
22540 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
22550 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
22560 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
22570 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
22580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22590 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
225a0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
225b0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
225c0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
225d0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
225e0 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
225f0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
22600 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
22610 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
22620 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
22630 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
22640 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
22650 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
22660 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
22670 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
22680 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
22690 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
226a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
226b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
226c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
226d0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
226e0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
226f0 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
22700 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
22710 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
22720 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
22730 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
22740 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
22750 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
22760 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
22770 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
22780 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
22790 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
227a0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
227b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
227c0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
227d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
227e0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
227f0 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
22800 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
22810 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e   **ppArg);..  in
22820 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
22830 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
22840 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
22850 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ew);.};../*.** T
22860 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
22870 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
22880 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
22890 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
228a0 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
228b0 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
228c0 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
228d0 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
228e0 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
228f0 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
22900 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
22910 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
22920 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
22930 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
22940 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
22950 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
22960 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
22970 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
22980 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
22990 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
229a0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
229b0 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
229c0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
229d0 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ts of the.** for
229e0 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20  m:.**.**        
229f0 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a   column OP expr.
22a00 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69  **.** Where OP i
22a10 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
22a20 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
22a30 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69  .  .** The parti
22a40 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
22a50 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
22a60 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
22a70 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
22a80 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
22a90 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73  red in .** aCons
22aa0 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e  traint[].iColumn
22ab0 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  .  aConstraint[]
22ac0 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
22ad0 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
22ae0 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
22af0 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
22b00 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
22b10 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
22b20 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
22b30 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
22b40 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nnot..**.** The 
22b50 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
22b60 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
22b70 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
22b80 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
22b90 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
22ba0 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
22bb0 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45  tions to the WHE
22bc0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
22bd0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
22be0 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
22bf0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
22c00 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
22c10 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
22c20 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  le..** The aCons
22c30 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f  traint[] array o
22c40 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52  nly reports WHER
22c50 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
22c60 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a  n the correct.**
22c70 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72   form that refer
22c80 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
22c90 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
22ca0 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
22cb0 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f  **.** Informatio
22cc0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
22cd0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
22ce0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
22cf0 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72  y[]..** Each ter
22d00 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
22d10 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
22d20 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
22d30 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
22d40 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
22d50 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
22d60 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
22d70 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
22d80 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
22d90 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
22da0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49  s to xFilter.  I
22db0 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68  f argvIndex>0 th
22dc0 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d  en.** the right-
22dd0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
22de0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61   corresponding a
22df0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20  Constraint[] is 
22e00 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64  evaluated.** and
22e10 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67   becomes the arg
22e20 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20  vIndex-th entry 
22e30 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f  in argv.  If aCo
22e40 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
22e50 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
22e60 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
22e70 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
22e80 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
22e90 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
22ea0 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
22eb0 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
22ec0 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a  gain by SQLite..
22ed0 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d  **.** The idxNum
22ee0 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
22ef0 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
22f00 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
22f10 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69  xFilter..** sqli
22f20 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73  te3_free() is us
22f30 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
22f40 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49  r if needToFreeI
22f50 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
22f60 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
22f70 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
22f80 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
22f90 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63  xFilter will occ
22fa0 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
22fb0 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
22fc0 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
22fd0 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
22fe0 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
22ff0 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
23000 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
23010 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f   The estimatedCo
23020 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
23030 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
23040 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
23050 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
23060 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
23070 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
23080 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
23090 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
230a0 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
230b0 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
230c0 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
230d0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
230e0 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
230f0 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
23100 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
23110 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
23120 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
23130 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e    int nConstrain
23140 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t;           /* 
23150 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
23160 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
23170 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
23180 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
23190 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74  raint {.     int
231a0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
231b0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
231c0 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69   on left-hand si
231d0 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74  de of constraint
231e0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
231f0 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20  d char op;      
23200 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74     /* Constraint
23210 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20   operator */.   
23220 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
23230 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
23240 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
23250 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
23260 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65   */.     int iTe
23270 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20  rmOffset;       
23280 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
23290 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64  nally - xBestInd
232a0 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65  ex should ignore
232b0 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
232c0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
232d0 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45   /* Table of WHE
232e0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
232f0 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  aints */.  int n
23300 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
23310 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
23320 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
23330 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
23340 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
23350 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
23360 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
23370 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
23380 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
23390 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
233a0 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
233b0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
233c0 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
233d0 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
233e0 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
233f0 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
23400 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
23410 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20  /..  /* Outputs 
23420 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
23430 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
23440 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20  aint_usage {.   
23450 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20   int argvIndex; 
23460 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20            /* if 
23470 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  >0, constraint i
23480 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74  s part of argv t
23490 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20  o xFilter */.   
234a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
234b0 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20  mit;      /* Do 
234c0 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20  not code a test 
234d0 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61  for this constra
234e0 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  int */.  } *aCon
234f0 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20  straintUsage;.  
23500 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20  int idxNum;     
23510 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
23520 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65  mber used to ide
23530 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20  ntify the index 
23540 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74  */.  char *idxSt
23550 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  r;              
23560 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69  /* String, possi
23570 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  bly obtained fro
23580 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
23590 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f   */.  int needTo
235a0 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20  FreeIdxStr;     
235b0 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20   /* Free idxStr 
235c0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  using sqlite3_fr
235d0 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a  ee() if true */.
235e0 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e    int orderByCon
235f0 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20  sumed;       /* 
23600 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69  True if output i
23610 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65  s already ordere
23620 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73  d */.  double es
23630 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20  timatedCost;    
23640 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63    /* Estimated c
23650 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ost of using thi
23660 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64  s index */.};.#d
23670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
23680 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51  EX_CONSTRAINT_EQ
23690 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
236a0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
236b0 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64  RAINT_GT    4.#d
236c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
236d0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45  EX_CONSTRAINT_LE
236e0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
236f0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
23700 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23  RAINT_LT    16.#
23710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
23720 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
23730 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20  E    32.#define 
23740 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
23750 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34  STRAINT_MATCH 64
23760 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ../*.** This rou
23770 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20  tine is used to 
23780 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d  register a new m
23790 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20  odule name with 
237a0 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e  an SQLite.** con
237b0 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65  nection.  Module
237c0 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72   names must be r
237d0 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65  egistered before
237e0 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a   creating new.**
237f0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
23800 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f  on the module, o
23810 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70  r before using p
23820 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75  reexisting virtu
23830 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20  al.** tables of 
23840 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69  the module..*/.i
23850 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
23860 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
23870 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
23880 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
23890 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
238a0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
238b0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
238c0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
238d0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
238e0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
238f0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
23900 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74  ule *,    /* Met
23910 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
23920 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20  ule */.  void * 
23930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23940 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
23950 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
23960 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f  Connect */.);../
23970 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
23980 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  e is identical t
23990 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  o the sqlite3_cr
239a0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65  eate_module() me
239b0 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65  thod above,.** e
239c0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
239d0 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f  lows a destructo
239e0 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  r function to be
239f0 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69   specified. It i
23a00 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65  s.** even more e
23a10 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e  xperimental than
23a20 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65   the rest of the
23a30 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
23a40 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  API..*/.int sqli
23a50 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
23a60 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
23a70 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
23a80 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
23a90 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
23aa0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
23ab0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
23ac0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
23ad0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
23ae0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
23af0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
23b00 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *,    /* Methods
23b10 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
23b20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
23b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23b40 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
23b50 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
23b60 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
23b70 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
23b80 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
23b90 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
23ba0 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45  n */.);../*.** E
23bb0 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  very module impl
23bc0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
23bd0 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
23be0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
23bf0 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63  cture.** to desc
23c00 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
23c10 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  r instance of th
23c20 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
23c30 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
23c40 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
23c50 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
23c60 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
23c70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
23c80 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73     The.** purpos
23c90 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
23ca0 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
23cb0 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
23cc0 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e   that are common
23cd0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  .** to all modul
23ce0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23cf0 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  s..**.** Virtual
23d00 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
23d10 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
23d20 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
23d30 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
23d40 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
23d50 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
23d60 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ) to zErrMsg.  T
23d70 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
23d80 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
23d90 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
23da0 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
23db0 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
23dc0 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f  3_free().** prio
23dd0 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61  r to assigning a
23de0 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a   new string to z
23df0 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74  ErrMsg.  After t
23e00 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
23e10 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
23e20 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
23e30 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
23e40 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
23e50 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
23e60 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
23e70 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
23e80 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
23e90 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
23ea0 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73    Note.** that s
23eb0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
23ec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65   and sqlite3_fre
23ed0 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20  e() are used on 
23ee0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
23ef0 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75  d.** since virtu
23f00 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  al tables are co
23f10 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74  mmonly implement
23f20 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65  ed in loadable e
23f30 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a  xtensions which.
23f40 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61  ** do not have a
23f50 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33  ccess to sqlite3
23f60 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c  MPrintf() or sql
23f70 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73  ite3Free()..*/.s
23f80 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
23f90 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
23fa0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
23fb0 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
23fc0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
23fd0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
23fe0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
23ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24000 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
24010 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a  lly */.  char *z
24020 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20  ErrMsg;         
24030 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
24040 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73  r message from s
24050 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
24060 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
24070 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
24080 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
24090 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
240a0 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
240b0 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75  ;../* Every modu
240c0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
240d0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
240e0 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  s of the followi
240f0 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  ng structure.** 
24100 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
24110 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
24120 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20  nto the virtual 
24130 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73  table and are us
24140 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68  ed.** to loop th
24150 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61  rough the virtua
24160 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72  l table.  Cursor
24170 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
24180 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e  ing the.** xOpen
24190 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
241a0 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64  odule.  Each mod
241b0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
241c0 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a  on will define.*
241d0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
241e0 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74   a cursor struct
241f0 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20  ure to suit its 
24200 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  own needs..**.**
24210 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   This superclass
24220 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72   exists in order
24230 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64   to define field
24240 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20  s of the cursor 
24250 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d  that.** are comm
24260 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d  on to all implem
24270 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74  entations..*/.st
24280 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
24290 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c  b_cursor {.  sql
242a0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
242b0 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61  ;      /* Virtua
242c0 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20  l table of this 
242d0 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56  cursor */.  /* V
242e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
242f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
24300 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
24310 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
24320 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54  s */.};../*.** T
24330 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78  he xCreate and x
24340 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20  Connect methods 
24350 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20  of a module use 
24360 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
24370 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20  I.** to declare 
24380 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20  the format (the 
24390 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79  names and dataty
243a0 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  pes of the colum
243b0 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69  ns) of.** the vi
243c0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65  rtual tables the
243d0 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a  y implement..*/.
243e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  int sqlite3_decl
243f0 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33  are_vtab(sqlite3
24400 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
24410 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f  CreateTable);../
24420 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
24430 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  les can provide 
24440 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
24450 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66  ementations of f
24460 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e  unctions.** usin
24470 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74  g the xFindFunct
24480 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74  ion method.  But
24490 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
244a0 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
244b0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
244c0 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
244d0 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
244e0 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65  ** This API make
244f0 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
24500 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
24510 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
24520 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
24530 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
24540 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
24550 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
24560 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
24570 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
24580 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
24590 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
245a0 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  ated.  The imple
245b0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
245c0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
245d0 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
245e0 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
245f0 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
24600 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
24610 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
24620 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
24630 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
24640 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
24650 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64   be a place-hold
24660 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  er function that
24670 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64   can be overload
24680 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c  ed.** by virtual
24690 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54   tables..**.** T
246a0 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62  his API should b
246b0 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72  e considered par
246c0 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
246d0 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65   table interface
246e0 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78  ,.** which is ex
246f0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73  perimental and s
24700 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
24710 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24720 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69  _overload_functi
24730 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  on(sqlite3*, con
24740 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61  st char *zFuncNa
24750 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a  me, int nArg);..
24760 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
24770 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
24780 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
24790 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65  sm defined above
247a0 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20   (back up.** to 
247b0 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b  a comment remark
247c0 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20  ably similar to 
247d0 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72  this one) is cur
247e0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
247f0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
24800 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
24810 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
24820 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
24830 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
24840 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
24850 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
24860 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
24870 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
24880 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
24890 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
248a0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
248b0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
248c0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
248d0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
248e0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
248f0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
24900 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
24910 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  **.****** EXPERI
24920 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
24930 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
24940 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
24950 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a  ********.*/../*.
24960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
24970 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
24980 20 42 4c 4f 42 20 7b 46 31 37 38 30 30 7d 0a 2a   BLOB {F17800}.*
24990 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
249a0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
249b0 67 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  g opaque structu
249c0 72 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a  re is used to .*
249d0 2a 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62  * represent an b
249e0 6c 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62  lob-handle.  A b
249f0 6c 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72  lob-handle is cr
24a00 65 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  eated by.** [sql
24a10 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
24a20 5d 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  ] and destroyed 
24a30 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
24a40 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68  _close()]..** Th
24a50 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
24a60 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
24a70 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
24a80 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
24a90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
24aa0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d  read or write sm
24ab0 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20  all subsections 
24ac0 6f 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20  of the blob..** 
24ad0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
24ae0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
24af0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24b00 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
24b10 62 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a  blob in bytes..*
24b20 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
24b30 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71   sqlite3_blob sq
24b40 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a  lite3_blob;../*.
24b50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
24b60 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63  n A BLOB For Inc
24b70 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31  remental I/O {F1
24b80 37 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e  7810}.**.** Open
24b90 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65   a handle to the
24ba0 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e   blob located in
24bb0 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75   row iRow,, colu
24bc0 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20  mn zColumn, .** 
24bd0 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20  table zTable in 
24be0 64 61 74 61 62 61 73 65 20 7a 44 62 2e 20 69 2e  database zDb. i.
24bf0 65 2e 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62  e. the same blob
24c00 20 74 68 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62   that would.** b
24c10 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
24c20 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
24c30 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
24c40 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
24c50 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69   WHERE rowid = i
24c60 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  Row;.** </pre>.*
24c70 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
24c80 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
24c90 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f  on-zero, the blo
24ca0 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  b is opened for 
24cb0 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69  .** read and wri
24cc0 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
24cd0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c   is zero, the bl
24ce0 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  ob is opened for
24cf0 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73   read .** access
24d00 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
24d10 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
24d20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
24d30 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c  the new .** [sql
24d40 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
24d50 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74   handle] is writ
24d60 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a  ten to *ppBlob..
24d70 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  ** Otherwise an 
24d80 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
24d90 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61  turned and .** a
24da0 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e  ny value written
24db0 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75   to *ppBlob shou
24dc0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
24dd0 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a  y the caller..**
24de0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   This function s
24df0 65 74 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ets the database
24e00 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f  -handle error co
24e10 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a  de and message.*
24e20 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  * accessible via
24e30 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
24e40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
24e50 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
24e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
24e70 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
24e80 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
24e90 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
24ea0 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
24eb0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
24ec0 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
24ed0 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
24ee0 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
24ef0 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
24f00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24f10 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20  :  Close A BLOB 
24f20 48 61 6e 64 6c 65 20 7b 46 31 37 38 33 30 7d 0a  Handle {F17830}.
24f30 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f  **.** Close an o
24f40 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  pen [sqlite3_blo
24f50 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d  b | blob handle]
24f60 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20  ..**.** Closing 
24f70 61 20 42 4c 4f 42 20 6d 69 67 68 74 20 63 61 75  a BLOB might cau
24f80 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  se the current t
24f90 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f  ransaction to co
24fa0 6d 6d 69 74 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  mmit..** If any 
24fb0 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
24fc0 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
24fd0 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
24fe0 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
24ff0 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
25000 72 61 74 69 6f 6e 2e 20 20 43 6c 6f 73 69 6e 67  ration.  Closing
25010 20 74 68 65 20 42 4c 4f 42 20 66 6f 72 63 65 73   the BLOB forces
25020 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
25030 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
25040 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
25050 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
25060 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
25070 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
25080 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
25090 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20  is closed.  Any 
250a0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
250b0 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
250c0 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
250d0 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
250e0 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a  eturn value..**.
250f0 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63  ** The BLOB is c
25100 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f  losed unconditio
25110 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20  nally.  Even if 
25120 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
25130 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  urns.** an error
25140 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20   code, the BLOB 
25150 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e  is still closed.
25160 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
25170 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74  blob_close(sqlit
25180 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
25190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52 65  ** CAPI3REF:  Re
251a0 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
251b0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46   An Open BLOB {F
251c0 31 37 38 30 35 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  17805}.**.** {F1
251d0 36 38 30 36 7d 20 52 65 74 75 72 6e 20 74 68 65  6806} Return the
251e0 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
251f0 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65 73  f the blob acces
25200 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f 70  sible via the op
25210 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
25220 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64  blob | blob-hand
25230 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 61 6e  le] passed as an
25240 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e   argument..*/.in
25250 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62  t sqlite3_blob_b
25260 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f  ytes(sqlite3_blo
25270 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
25280 49 33 52 45 46 3a 20 20 52 65 61 64 20 44 61 74  I3REF:  Read Dat
25290 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e  a From A BLOB In
252a0 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 37  crementally {F17
252b0 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  850}.**.** This 
252c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
252d0 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
252e0 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b  om an open .** [
252f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
25300 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  lob-handle] into
25310 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69   a caller suppli
25320 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20  ed buffer..** n 
25330 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
25340 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
25350 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20 74  ffer.** z from t
25360 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74  he open blob, st
25370 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
25380 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20   iOffset..**.** 
25390 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49  On success, SQLI
253a0 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
253b0 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  d. Otherwise, an
253c0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
253d0 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f  OR | SQLite erro
253e0 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  r code] or an.**
253f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
25400 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65  EAD | extended e
25410 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
25420 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
25430 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
25440 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
25450 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c   void *z, int n,
25460 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
25470 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25480 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f   Write Data Into
25490 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
254a0 74 61 6c 6c 79 20 7b 46 31 37 38 37 30 7d 0a 2a  tally {F17870}.*
254b0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
254c0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72  on is used to wr
254d0 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e  ite data into an
254e0 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
254f0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
25500 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73  andle] from a us
25510 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66  er supplied buff
25520 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f  er..** n bytes o
25530 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
25540 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65  d from the buffe
25550 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  r.** pointed to 
25560 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70  by z into the op
25570 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
25580 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
25590 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  set..**.** If th
255a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  e [sqlite3_blob 
255b0 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70  | blob-handle] p
255c0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
255d0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  st argument.** w
255e0 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f  as not opened fo
255f0 72 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  r writing (the f
25600 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
25610 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
25620 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20  open()].*** was 
25630 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63  zero), this func
25640 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
25650 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
25660 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
25670 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
25680 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
25690 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 69 74   of the blob, it
256a0 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
256b0 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
256c0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  the size of a bl
256d0 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  ob using this AP
256e0 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 74 20  I. If.** offset 
256f0 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
25700 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f  than n bytes fro
25710 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
25720 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49   blob, .** [SQLI
25730 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
25740 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
25750 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a  a is written..**
25760 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
25770 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
25780 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65  urned. Otherwise
25790 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  , an .** [SQLITE
257a0 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20  _ERROR | SQLite 
257b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
257c0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  n.** [SQLITE_IOE
257d0 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
257e0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
257f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69  s returned..*/.i
25800 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
25810 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c  write(sqlite3_bl
25820 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ob *, const void
25830 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
25840 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
25850 20 43 41 50 49 33 52 45 46 3a 20 20 56 69 72 74   CAPI3REF:  Virt
25860 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20  ual File System 
25870 4f 62 6a 65 63 74 73 20 7b 46 31 31 32 30 30 7d  Objects {F11200}
25880 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c  .**.** A virtual
25890 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53   filesystem (VFS
258a0 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  ) is an [sqlite3
258b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  _vfs] object.** 
258c0 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73  that SQLite uses
258d0 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20   to interact.** 
258e0 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79  with the underly
258f0 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
25900 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c  stem.  Most buil
25910 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a  ds come with a.*
25920 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74  * single default
25930 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70   VFS that is app
25940 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65  ropriate for the
25950 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
25960 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e  ** New VFSes can
25970 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
25980 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65  nd existing VFSe
25990 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73  s can be unregis
259a0 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f  tered..** The fo
259b0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
259c0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e  es are provided.
259d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
259e0 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e  e3_vfs_find() in
259f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25a00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56  a pointer to a V
25a10 46 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a 20  FS given its.** 
25a20 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 65  name.  Names are
25a30 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
25a40 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
25a50 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a   match, a NULL.*
25a60 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  * pointer is ret
25a70 75 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 4e  urned.  If zVfsN
25a80 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ame is NULL then
25a90 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a   the default .**
25aa0 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64   VFS is returned
25ab0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65  ..**.** New VFSe
25ac0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
25ad0 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66   with sqlite3_vf
25ae0 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20 45  s_register().  E
25af0 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20 62  ach.** new VFS b
25b00 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75  ecomes the defau
25b10 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61  lt VFS if the ma
25b20 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73  keDflt flag is s
25b30 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20  et..** The same 
25b40 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73  VFS can be regis
25b50 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
25b60 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a  imes without inj
25b70 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20  ury..** To make 
25b80 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
25b90 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
25ba0 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
25bb0 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
25bc0 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
25bd0 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64  g set.  If two d
25be0 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77  ifferent VFSes w
25bf0 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  ith the.** same 
25c00 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65  name are registe
25c10 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f  red, the behavio
25c20 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
25c30 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
25c40 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
25c50 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
25c60 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
25c70 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
25c80 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
25c90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a  undefined..** .*
25ca0 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56  * Unregister a V
25cb0 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
25cc0 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
25cd0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
25ce0 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c  ** If the defaul
25cf0 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
25d00 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
25d10 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
25d20 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
25d30 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
25d40 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
25d50 72 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c  rbitrary..*/.sql
25d60 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65  ite3_vfs *sqlite
25d70 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74  3_vfs_find(const
25d80 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29   char *zVfsName)
25d90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
25da0 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  s_register(sqlit
25db0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b  e3_vfs*, int mak
25dc0 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69  eDflt);.int sqli
25dd0 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
25de0 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29  er(sqlite3_vfs*)
25df0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25e00 46 3a 20 4d 75 74 65 78 65 73 20 7b 46 31 37 30  F: Mutexes {F170
25e10 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00}.**.** The SQ
25e20 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
25e30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
25e40 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63  r thread.** sync
25e50 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68  hronization.  Th
25e60 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
25e70 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
25e80 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
25e90 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
25ea0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
25eb0 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
25ec0 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
25ed0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
25ee0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
25ef0 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
25f00 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
25f10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25f20 73 20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d  s .** of these m
25f30 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20  utex routines.  
25f40 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69  An appropriate i
25f50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
25f60 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74   is selected aut
25f70 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f  omatically at co
25f80 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65  mpile-time.  The
25f90 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d   following.** im
25fa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72  plementations ar
25fb0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  e available in t
25fc0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a  he SQLite core:.
25fd0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
25fe0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
25ff0 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_OS2.** <li>   
26000 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
26010 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  READ.** <li>   S
26020 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a  QLITE_MUTEX_W32.
26030 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
26040 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c  _MUTEX_NOOP.** <
26050 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
26060 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
26070 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26080 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74  is a set of rout
26090 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f  ines .** that do
260a0 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69  es no real locki
260b0 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70  ng and is approp
260c0 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e  riate for use in
260d0 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68   .** a single-th
260e0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
260f0 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  on.  The SQLITE_
26100 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51  MUTEX_OS2,.** SQ
26110 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
26120 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AD, and SQLITE_M
26130 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65  UTEX_W32 impleme
26140 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
26150 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
26160 75 73 65 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69  use on os/2, uni
26170 78 2c 20 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a  x, and windows..
26180 2a 2a 20 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  ** .** If SQLite
26190 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
261a0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  h the SQLITE_MUT
261b0 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f  EX_APPDEF prepro
261c0 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20  cessor.** macro 
261d0 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d  defined (with "-
261e0 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50  DSQLITE_MUTEX_AP
261f0 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e  PDEF=1"), then n
26200 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  o mutex.** imple
26210 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63  mentation is inc
26220 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c  luded with the l
26230 69 62 72 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20  ibrary.  The.** 
26240 6d 75 74 65 78 20 69 6e 74 65 72 66 61 63 65 20  mutex interface 
26250 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
26260 20 68 65 72 65 20 62 65 63 6f 6d 65 20 65 78 74   here become ext
26270 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e  ernal.** referen
26280 63 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ces in the SQLit
26290 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68  e library for wh
262a0 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ich implementati
262b0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70  ons.** must be p
262c0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 61  rovided by the a
262d0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  pplication.  Thi
262e0 73 20 66 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77  s facility allow
262f0 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  s an.** applicat
26300 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ion that links a
26310 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 74 6f  gainst SQLite to
26320 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e   provide its own
26330 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
26340 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f 75 74  entation without
26350 20 68 61 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66   having to modif
26360 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
26370 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
26380 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
26390 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63  () routine alloc
263a0 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75  ates a new.** mu
263b0 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20  tex and returns 
263c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
263d0 20 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20    If it returns 
263e0 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
263f0 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
26400 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
26410 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 0a  ocated.  SQLite.
26420 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69  ** will unwind i
26430 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74  ts stack and ret
26440 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 54  urn an error.  T
26450 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
26460 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
26470 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f  alloc() is one o
26480 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
26490 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a  constants:.**.**
264a0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
264b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
264c0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
264d0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
264e0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
264f0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
26500 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  STER.** <li>  SQ
26510 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
26520 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_MEM.** <li>  S
26530 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
26540 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20  IC_MEM2.** <li> 
26550 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
26560 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69  ATIC_PRNG.** <li
26570 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
26580 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f  STATIC_LRU.** </
26590 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
265a0 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  rst two constant
265b0 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  s cause sqlite3_
265c0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f  mutex_alloc() to
265d0 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77   create.** a new
265e0 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77   mutex.  The new
265f0 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
26600 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
26610 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
26620 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
26630 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
26640 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
26650 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
26660 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
26670 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
26680 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
26690 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
266a0 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
266b0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
266c0 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
266d0 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
266e0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
266f0 20 74 6f 2e 20 20 42 75 74 20 53 51 4c 69 74 65   to.  But SQLite
26700 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65   will only reque
26710 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d  st a recursive m
26720 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73  utex in.** cases
26730 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79   where it really
26740 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 49 66 20   needs one.  If 
26750 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63  a faster non-rec
26760 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20  ursive mutex.** 
26770 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
26780 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74  s available on t
26790 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d  he host platform
267a0 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73  , the mutex subs
267b0 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72  ystem.** might r
267c0 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74  eturn such a mut
267d0 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ex in response t
267e0 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  o SQLITE_MUTEX_F
267f0 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  AST..**.** The o
26800 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
26810 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
26820 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
26830 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
26840 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
26850 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
26860 67 20 6d 75 74 65 78 2e 20 20 46 6f 75 72 20 73  g mutex.  Four s
26870 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
26880 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
26890 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
268a0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
268b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
268c0 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
268d0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
268e0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
268f0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
26900 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
26910 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
26920 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
26930 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
26940 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
26950 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
26960 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
26970 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
26980 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
26990 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
269a0 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
269b0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 69 66  .** Note that if
269c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61   one of the dyna
269d0 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65  mic mutex parame
269e0 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ters (SQLITE_MUT
269f0 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51  EX_FAST.** or SQ
26a00 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
26a10 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68  SIVE) is used th
26a20 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  en sqlite3_mutex
26a30 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75  _alloc().** retu
26a40 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20  rns a different 
26a50 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63  mutex on every c
26a60 61 6c 6c 2e 20 20 42 75 74 20 66 6f 72 20 74 68  all.  But for th
26a70 65 20 73 74 61 74 69 63 20 0a 2a 2a 20 6d 75 74  e static .** mut
26a80 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61  ex types, the sa
26a90 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75  me mutex is retu
26aa0 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61  rned on every ca
26ab0 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74  ll that has.** t
26ac0 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d  he same type num
26ad0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ber..**.** The s
26ae0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
26af0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c  e() routine deal
26b00 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 6f  locates a previo
26b10 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  usly.** allocate
26b20 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e  d dynamic mutex.
26b30 20 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65    SQLite is care
26b40 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74  ful to deallocat
26b50 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d  e every.** dynam
26b60 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74  ic mutex that it
26b70 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65   allocates.  The
26b80 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
26b90 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 20   must not be in 
26ba0 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65  .** use when the
26bb0 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65  y are deallocate
26bc0 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20 74  d.  Attempting t
26bd0 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73  o deallocate a s
26be0 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72  tatic.** mutex r
26bf0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
26c00 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20 53  ned behavior.  S
26c10 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c  QLite never deal
26c20 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61  locates.** a sta
26c30 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a  tic mutex..**.**
26c40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
26c50 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
26c60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
26c70 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
26c80 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
26c90 61 20 6d 75 74 65 78 2e 20 20 49 66 20 61 6e 6f  a mutex.  If ano
26ca0 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61  ther thread is a
26cb0 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68  lready within th
26cc0 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69  e mutex,.** sqli
26cd0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
26ce0 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64  ) will block and
26cf0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
26d00 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ry() will return
26d10 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
26d20 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75    The sqlite3_mu
26d30 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
26d40 61 63 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ace returns SQLI
26d50 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73 75  TE_OK.** upon su
26d60 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20  ccessful entry. 
26d70 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64   Mutexes created
26d80 20 75 73 69 6e 67 20 53 51 4c 49 54 45 5f 4d 55   using SQLITE_MU
26d90 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61  TEX_RECURSIVE ca
26da0 6e 0a 2a 2a 20 62 65 20 65 6e 74 65 72 65 64 20  n.** be entered 
26db0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62  multiple times b
26dc0 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
26dd0 64 2e 20 20 49 6e 20 73 75 63 68 20 63 61 73 65  d.  In such case
26de0 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
26df0 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
26e00 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
26e10 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
26e20 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
26e30 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 49 66 20   can enter.  If 
26e40 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
26e50 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
26e60 6e 79 20 6f 74 68 65 72 20 6b 69 6e 64 20 6f 66  ny other kind of
26e70 20 6d 75 74 65 78 0a 2a 2a 20 6d 6f 72 65 20 74   mutex.** more t
26e80 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
26e90 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
26ea0 6e 65 64 2e 20 20 20 53 51 4c 69 74 65 20 77 69  ned.   SQLite wi
26eb0 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
26ec0 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
26ed0 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
26ee0 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a   of mutexes..**.
26ef0 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20  ** Some systems 
26f00 28 65 78 3a 20 77 69 6e 64 6f 77 73 39 35 29 20  (ex: windows95) 
26f10 64 6f 20 6e 6f 74 20 74 68 65 20 6f 70 65 72 61  do not the opera
26f20 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 65 64  tion implemented
26f30 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   by.** sqlite3_m
26f40 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20  utex_try().  On 
26f50 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73  those systems, s
26f60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
26f70 28 29 20 77 69 6c 6c 0a 2a 2a 20 61 6c 77 61 79  () will.** alway
26f80 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  s return SQLITE_
26f90 42 55 53 59 2e 20 20 54 68 65 20 53 51 4c 69 74  BUSY.  The SQLit
26fa0 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72  e core only ever
26fb0 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33   uses.** sqlite3
26fc0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20  _mutex_try() as 
26fd0 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  an optimization 
26fe0 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70  so this is accep
26ff0 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  table behavior..
27000 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27010 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20  3_mutex_leave() 
27020 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20  routine exits a 
27030 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a  mutex that was.*
27040 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74  * previously ent
27050 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65  ered by the same
27060 20 74 68 72 65 61 64 2e 20 20 54 68 65 20 62 65   thread.  The be
27070 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
27080 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75  efined if the mu
27090 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65  tex is not curre
270a0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  ntly entered by 
270b0 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74  the.** calling t
270c0 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20  hread or is not 
270d0 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61  currently alloca
270e0 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ted.  SQLite wil
270f0 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69  l.** never do ei
27100 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ther..**.** See 
27110 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d  also: [sqlite3_m
27120 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64  utex_held()] and
27130 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
27140 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73  notheld()]..*/.s
27150 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
27160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
27170 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  c(int);.void sql
27180 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
27190 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
271a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
271b0 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65  tex_enter(sqlite
271c0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
271d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
271e0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
271f0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
27200 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74  utex_leave(sqlit
27210 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
27220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
27230 65 78 20 56 65 72 69 66 63 61 74 69 6f 6e 20 52  ex Verifcation R
27240 6f 75 74 69 6e 65 73 20 7b 46 31 37 30 38 30 7d  outines {F17080}
27250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27260 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
27270 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
27280 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74  x_notheld() rout
27290 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65  ines.** are inte
272a0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  nded for use ins
272b0 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ide assert() sta
272c0 74 65 6d 65 6e 74 73 2e 20 7b 46 31 37 30 38 31  tements. {F17081
272d0 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  } The SQLite cor
272e0 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20  e.** never uses 
272f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65  these routines e
27300 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20  xcept inside an 
27310 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 70  assert() and app
27320 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  lications.** are
27330 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c   advised to foll
27340 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74  ow the lead of t
27350 68 65 20 63 6f 72 65 2e 20 20 7b 46 31 37 30 38  he core.  {F1708
27360 32 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79  2} The core only
27370 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70  .** provides imp
27380 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
27390 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
273a0 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
273b0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  led.** with the 
273c0 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61  SQLITE_DEBUG fla
273d0 67 2e 20 20 7b 55 31 37 30 38 33 7d 20 45 78 74  g.  {U17083} Ext
273e0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c  ernal mutex impl
273f0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
27400 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64  re only required
27410 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73   to provide thes
27420 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51  e routines if SQ
27430 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a  LITE_DEBUG is.**
27440 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20   defined and if 
27450 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65  NDEBUG is not de
27460 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fined..**.** {F1
27470 37 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74  7083} These rout
27480 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ines should retu
27490 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 6d  rn true if the m
274a0 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61 72  utex in their ar
274b0 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c  gument.** is hel
274c0 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72  d or not held, r
274d0 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20  espectively, by 
274e0 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
274f0 61 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ad. {END}.**.** 
27500 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70  {X17084} The imp
27510 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
27520 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70  ot required to p
27530 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73  rovided versions
27540 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75   of these.** rou
27550 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61  tines that actua
27560 6c 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20  lly work..** If 
27570 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
27580 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  on does not prov
27590 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76  ide working.** v
275a0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
275b0 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68   routines, it sh
275c0 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72  ould at least pr
275d0 6f 76 69 64 65 20 73 74 75 62 73 0a 2a 2a 20 74  ovide stubs.** t
275e0 68 61 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  hat always retur
275f0 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f  n true so that o
27600 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20  ne does not get 
27610 73 70 75 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65  spurious.** asse
27620 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 20  rtion failures. 
27630 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  {END}.**.** {F17
27640 30 38 35 7d 20 49 66 20 74 68 65 20 61 72 67 75  085} If the argu
27650 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
27660 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20  mutex_held() is 
27670 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
27680 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hen.** the routi
27690 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ne should return
276a0 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20   1.  {END} This 
276b0 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e  seems counter-in
276c0 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a  tuitive since.**
276d0 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74   clearly the mut
276e0 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c  ex cannot be hel
276f0 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74  d if it does not
27700 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65   exist.  But the
27710 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74  .** the reason t
27720 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f  he mutex does no
27730 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75  t exist is becau
27740 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20  se the build is 
27750 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74  not.** using mut
27760 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f  exes.  And we do
27770 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73   not want the as
27780 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e  sert() containin
27790 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f  g the.** call to
277a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
277b0 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73  eld() to fail, s
277c0 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  o a non-zero ret
277d0 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70  urn is.** the ap
277e0 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20  propriate thing 
277f0 74 6f 20 64 6f 2e 20 20 7b 46 31 37 30 38 36 7d  to do.  {F17086}
27800 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
27810 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a  ex_notheld() .**
27820 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
27830 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20  d also return 1 
27840 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c  when given a NUL
27850 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e  L pointer..*/.in
27860 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
27870 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
27880 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ex*);.int sqlite
27890 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
278a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
278b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
278c0 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b 46  : Mutex Types {F
278d0 31 37 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  17001}.**.** {F1
278e0 37 30 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7002} The [sqlit
278f0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
27900 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65  ] interface take
27910 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
27920 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ent.** which is 
27930 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
27940 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 20  eger constants. 
27950 7b 45 4e 44 7d 0a 2a 2f 0a 23 64 65 66 69 6e 65  {END}.*/.#define
27960 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
27970 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30  ST             0
27980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27990 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
279a0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
279b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
279c0 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32  ATIC_MASTER    2
279d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
279e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
279f0 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c         3  /* sql
27a00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f  ite3_malloc() */
27a10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27a20 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
27a30 32 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c  2      4  /* sql
27a40 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
27a50 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  ory() */.#define
27a60 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
27a70 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35  ATIC_PRNG      5
27a80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e    /* sqlite3_ran
27a90 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  dom() */.#define
27aa0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
27ab0 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36  ATIC_LRU       6
27ac0 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
27ad0 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  st */../*.** CAP
27ae0 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c  I3REF: Low-Level
27af0 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61   Control Of Data
27b00 62 61 73 65 20 46 69 6c 65 73 20 7b 46 31 31 33  base Files {F113
27b10 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30  00}.**.** {F1130
27b20 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
27b30 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
27b40 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
27b50 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f  a direct call to
27b60 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e   the.** xFileCon
27b70 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20  trol method for 
27b80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
27b90 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
27ba0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
27bb0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
27bc0 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66  database identif
27bd0 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
27be0 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 31  d argument. {F11
27bf0 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65  302} The.** name
27c00 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
27c10 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73   is the name ass
27c20 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74  igned to the dat
27c30 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20  abase by the.** 
27c40 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74  <a href="lang_at
27c50 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43  tach.html">ATTAC
27c60 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e  H</a> SQL comman
27c70 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68  d that opened th
27c80 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b  e.** database. {
27c90 46 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72  F11303} To contr
27ca0 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  ol the main data
27cb0 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74  base file, use t
27cc0 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a  he name "main".*
27cd0 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * or a NULL poin
27ce0 74 65 72 2e 20 7b 46 31 31 33 30 34 7d 20 54 68  ter. {F11304} Th
27cf0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
27d00 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
27d10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
27d20 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65   are passed dire
27d30 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20  ctly through to 
27d40 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
27d50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20  hird parameters 
27d60 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43  of.** the xFileC
27d70 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20  ontrol method.  
27d80 7b 46 31 31 33 30 35 7d 20 54 68 65 20 72 65 74  {F11305} The ret
27d90 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
27da0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a   xFileControl.**
27db0 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20   method becomes 
27dc0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
27dd0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
27de0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 36 7d  ..**.** {F11306}
27df0 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
27e00 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d  arameter (zDbNam
27e10 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  e) does not matc
27e20 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e  h the name of an
27e30 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  y.** open databa
27e40 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51  se file, then SQ
27e50 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65  LITE_ERROR is re
27e60 74 75 72 6e 65 64 2e 20 7b 46 31 31 33 30 37 7d  turned. {F11307}
27e70 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63   This error.** c
27e80 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d  ode is not remem
27e90 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e  bered and will n
27ea0 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62  ot be recalled b
27eb0 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
27ec0 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  de()].** or [sql
27ed0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20  ite3_errmsg()]. 
27ee0 7b 55 31 31 33 30 37 7d 20 54 68 65 20 75 6e 64  {U11307} The und
27ef0 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e  erlying xFileCon
27f00 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68  trol method migh
27f10 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e  t.** also return
27f20 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
27f30 7b 55 31 31 33 30 38 7d 20 54 68 65 72 65 20 69  {U11308} There i
27f40 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74  s no way to dist
27f50 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a  inguish between.
27f60 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20  ** an incorrect 
27f70 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53  zDbName and an S
27f80 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75  QLITE_ERROR retu
27f90 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65  rn from the unde
27fa0 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43  rlying.** xFileC
27fb0 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b  ontrol method. {
27fc0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  END}.**.** See a
27fd0 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  lso: [SQLITE_FCN
27fe0 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f  TL_LOCKSTATE].*/
27ff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  .int sqlite3_fil
28000 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65  e_control(sqlite
28010 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
28020 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c  zDbName, int op,
28030 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
28040 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68  Undo the hack th
28050 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61  at converts floa
28060 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73  ting point types
28070 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a   to integer for.
28080 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f  ** builds on pro
28090 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20  cessors without 
280a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
280b0 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65  upport..*/.#ifde
280c0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
280d0 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75  OATING_POINT.# u
280e0 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64  ndef double.#end
280f0 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  if..#ifdef __cpl
28100 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64  usplus.}  /* End
28110 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20   of the 'extern 
28120 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65  "C"' block */.#e
28130 6e 64 69 66 0a 23 65 6e 64 69 66 0a              ndif.#endif.