/ Hex Artifact Content
Login

Artifact b16a7127dad4a3e5b1b26b3d64241f3373aa12ea:


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 37 20 32 30 30 37 2f  in,v 1.277 2007/
05f0: 31 32 2f 31 32 20 31 32 3a 32 35 3a 32 32 20 64  12/12 12:25:22 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 23 64 65 66 69  10011} The #defi
0860: 6e 65 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ne in the sqlite
0870: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 20  3.h header file 
0880: 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 49 54 45 5f  named.** SQLITE_
0890: 56 45 52 53 49 4f 4e 20 72 65 73 6f 6c 76 65 73  VERSION resolves
08a0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
08b0: 65 72 61 6c 20 74 68 61 74 20 69 64 65 6e 74 69  eral that identi
08c0: 66 69 65 73 0a 2a 2a 20 74 68 65 20 76 65 72 73  fies.** the vers
08d0: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
08e0: 65 20 6c 69 62 72 61 72 79 20 69 6e 20 74 68 65  e library in the
08f0: 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 2c   format "X.Y.Z",
0900: 20 77 68 65 72 65 0a 2a 2a 20 58 20 69 73 20 74   where.** X is t
0910: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0920: 20 6e 75 6d 62 65 72 2c 20 59 20 69 73 20 74 68   number, Y is th
0930: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
0940: 6e 75 6d 62 65 72 20 61 6e 64 20 5a 0a 2a 2a 20  number and Z.** 
0950: 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e  is the release n
0960: 75 6d 62 65 72 2e 20 20 54 68 65 20 58 2e 59 2e  umber.  The X.Y.
0970: 5a 20 6d 69 67 68 74 20 62 65 20 66 6f 6c 6c 6f  Z might be follo
0980: 77 65 64 20 62 79 20 22 61 6c 70 68 61 22 20 6f  wed by "alpha" o
0990: 72 20 22 62 65 74 61 22 2e 0a 2a 2a 20 7b 45 4e  r "beta"..** {EN
09a0: 44 7d 20 46 6f 72 20 65 78 61 6d 70 6c 65 20 22  D} For example "
09b0: 33 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a  3.1.1beta"..**.*
09c0: 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73  * The X value is
09d0: 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c   always 3 in SQL
09e0: 69 74 65 2e 20 20 54 68 65 20 58 20 76 61 6c 75  ite.  The X valu
09f0: 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  e only changes w
0a00: 68 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  hen.** backwards
0a10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69   compatibility i
0a20: 73 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20  s broken and we 
0a30: 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20  intend to never 
0a40: 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61 72  break.** backwar
0a50: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
0a60: 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65 20 6f  .  The Y value o
0a70: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0a80: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61  .** there are ma
0a90: 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61  jor feature enha
0aa0: 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  ncements that ar
0ab0: 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61  e forwards compa
0ac0: 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74  tible.** but not
0ad0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0ae0: 74 69 62 6c 65 2e 20 20 54 68 65 20 5a 20 76 61  tible.  The Z va
0af0: 6c 75 65 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  lue is increment
0b00: 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20  ed with.** each 
0b10: 72 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65  release but rese
0b20: 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65  ts back to 0 whe
0b30: 6e 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  n Y is increment
0b40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 31  ed..**.** {F1001
0b50: 34 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45  4} The SQLITE_VE
0b60: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65  RSION_NUMBER #de
0b70: 66 69 6e 65 20 72 65 73 6f 6c 76 65 73 20 74 6f  fine resolves to
0b80: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77   an integer.** w
0b90: 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 20 28  ith the value  (
0ba0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30  X*1000000 + Y*10
0bb0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c  00 + Z) where X,
0bc0: 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 61 73   Y, and Z are as
0bd0: 0a 2a 2a 20 77 69 74 68 20 53 51 4c 49 54 45 5f  .** with SQLITE_
0be0: 56 45 52 53 49 4f 4e 2e 20 7b 45 4e 44 7d 20 46  VERSION. {END} F
0bf0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20  or example, for 
0c00: 76 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 62 65  version "3.1.1be
0c10: 74 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 45 5f  ta", .** SQLITE_
0c20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 69  VERSION_NUMBER i
0c30: 73 20 73 65 74 20 74 6f 20 33 30 30 31 30 30 31  s set to 3001001
0c40: 2e 20 54 6f 20 64 65 74 65 63 74 20 69 66 20 74  . To detect if t
0c50: 68 65 79 20 61 72 65 20 75 73 69 6e 67 20 0a 2a  hey are using .*
0c60: 2a 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e 31 20  * version 3.1.1 
0c70: 6f 72 20 67 72 65 61 74 65 72 20 61 74 20 63 6f  or greater at co
0c80: 6d 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 6f 67  mpile time, prog
0c90: 72 61 6d 73 20 6d 61 79 20 75 73 65 20 74 68 65  rams may use the
0ca0: 20 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c 49 54   test .** (SQLIT
0cb0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0cc0: 3e 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a  >=3001001)..**.*
0cd0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0ce0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0cf0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
0d00: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0d10: 72 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  r()]..*/.#define
0d20: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
0d30: 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d          "--VERS-
0d40: 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  -".#define SQLIT
0d50: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0d60: 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45   --VERSION-NUMBE
0d70: 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  R--../*.** CAPI3
0d80: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
0d90: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
0da0: 6d 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a  mbers {F10020}.*
0db0: 2a 0a 2a 2a 20 7b 46 31 30 30 32 31 7d 20 54 68  *.** {F10021} Th
0dc0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
0dd0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 69 6e  sion_number() in
0de0: 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
0df0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 65 71  an integer.** eq
0e00: 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56  ual to [SQLITE_V
0e10: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
0e20: 20 7b 45 4e 44 7d 20 54 68 65 20 76 61 6c 75 65   {END} The value
0e30: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
0e40: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  this routine sho
0e50: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 64 69 66 66  uld only be diff
0e60: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 68  erent from the h
0e70: 65 61 64 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  eader values.** 
0e80: 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  if the applicati
0e90: 6f 6e 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 75  on is compiled u
0ea0: 73 69 6e 67 20 61 6e 20 73 71 6c 69 74 65 33 2e  sing an sqlite3.
0eb0: 68 20 68 65 61 64 65 72 20 66 72 6f 6d 20 61 0a  h header from a.
0ec0: 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 76 65 72  ** different ver
0ed0: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
0ee0: 68 61 6e 20 6c 69 62 72 61 72 79 2e 20 20 43 61  han library.  Ca
0ef0: 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65  utious programme
0f00: 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c  rs might.** incl
0f10: 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74  ude a check in t
0f20: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
0f30: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
0f40: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
0f50: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
0f60: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
0f70: 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 5b 53 51  he value .** [SQ
0f80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0f90: 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  BER]..**.** {F10
0fa0: 30 32 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33  022} The sqlite3
0fb0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
0fc0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
0fd0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
0fe0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  the.** [SQLITE_V
0ff0: 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 20  ERSION] string. 
1000: 7b 46 31 30 30 32 33 7d 20 54 68 65 20 73 71 6c  {F10023} The sql
1010: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1020: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1030: 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
1040: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
1050: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1060: 63 6f 6e 73 74 61 6e 74 2e 20 7b 45 4e 44 7d 20  constant. {END} 
1070: 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
1080: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1090: 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70 72 6f 76  ction.** is prov
10a0: 69 64 65 64 20 66 6f 72 20 44 4c 4c 20 75 73 65  ided for DLL use
10b0: 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e 6c 79 20  rs who can only 
10c0: 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
10d0: 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63 6f 6e 73   and not.** cons
10e0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
10f0: 20 44 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   DLL..*/.SQLITE_
1100: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
1110: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1120: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
1130: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1140: 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ion(void);.int s
1150: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1160: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1170: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1180: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
1190: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
11a0: 68 72 65 61 64 73 61 66 65 20 7b 46 31 30 31 30  hreadsafe {F1010
11b0: 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 31  0}.**.** {F10101
11c0: 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68  } The sqlite3_th
11d0: 72 65 61 64 73 61 66 65 28 29 20 72 6f 75 74 69  readsafe() routi
11e0: 6e 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65  ne returns nonze
11f0: 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
1200: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1210: 68 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e  h its mutexes en
1220: 61 62 6c 65 64 20 6f 72 20 7a 65 72 6f 20 69 66  abled or zero if
1230: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1240: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1250: 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 20 7b  exes disabled. {
1260: 45 4e 44 7d 20 20 49 66 20 74 68 69 73 0a 2a 2a  END}  If this.**
1270: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1280: 20 66 61 6c 73 65 2c 20 74 68 65 6e 20 69 74 20   false, then it 
1290: 69 73 20 6e 6f 74 20 73 61 66 65 20 66 6f 72 20  is not safe for 
12a0: 73 69 6d 75 6c 74 61 6e 65 6f 75 73 6c 79 0a 2a  simultaneously.*
12b0: 2a 20 72 75 6e 6e 69 6e 67 20 74 68 72 65 61 64  * running thread
12c0: 73 20 74 6f 20 62 6f 74 68 20 69 6e 76 6f 6b 65  s to both invoke
12d0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 61 6c 6c 79  es..**.** Really
12f0: 20 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e   all this routin
1300: 65 20 64 6f 65 73 20 69 73 20 72 65 74 75 72 6e  e does is return
1310: 20 74 72 75 65 20 69 66 20 53 51 4c 69 74 65 20   true if SQLite 
1320: 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1330: 77 69 74 68 20 74 68 65 20 2d 44 53 51 4c 49 54  with the -DSQLIT
1340: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f  E_THREADSAFE=1 o
1350: 70 74 69 6f 6e 20 61 6e 64 20 66 61 6c 73 65 20  ption and false 
1360: 69 66 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  if.** compiled w
1370: 69 74 68 20 2d 44 53 51 4c 49 54 45 5f 54 48 52  ith -DSQLITE_THR
1380: 45 41 44 53 41 46 45 3d 30 2e 20 20 49 66 20 53  EADSAFE=0.  If S
1390: 51 4c 69 74 65 20 75 73 65 73 20 61 6e 0a 2a 2a  QLite uses an.**
13a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13b0: 69 6e 65 64 20 6d 75 74 65 78 20 73 75 62 73 79  ined mutex subsy
13c0: 73 74 65 6d 2c 20 6d 61 6c 6c 6f 63 20 73 75 62  stem, malloc sub
13d0: 73 79 73 74 65 6d 2c 20 63 6f 6c 6c 61 74 69 6e  system, collatin
13e0: 67 0a 2a 2a 20 73 65 71 75 65 6e 63 65 2c 20 56  g.** sequence, V
13f0: 46 53 2c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  FS, SQL function
1400: 2c 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  , progress callb
1410: 61 63 6b 2c 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  ack, commit hook
1420: 2c 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 2c 20  ,.** extension, 
1430: 6f 72 20 6f 74 68 65 72 20 61 63 63 65 73 73 6f  or other accesso
1440: 72 69 65 73 20 61 6e 64 20 74 68 65 73 65 20 61  ries and these a
1450: 64 64 2d 6f 6e 73 20 61 72 65 20 6e 6f 74 0a 2a  dd-ons are not.*
1460: 2a 20 74 68 72 65 61 64 73 61 66 65 2c 20 74 68  * threadsafe, th
1470: 65 6e 20 63 6c 65 61 72 6c 79 20 74 68 65 20 63  en clearly the c
1480: 6f 6d 62 69 6e 61 74 69 6f 6e 20 77 69 6c 6c 20  ombination will 
1490: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
14a0: 65 0a 2a 2a 20 65 69 74 68 65 72 2e 20 20 48 65  e.** either.  He
14b0: 6e 63 65 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  nce, this routin
14c0: 65 20 6e 65 76 65 72 20 72 65 70 6f 72 74 73 20  e never reports 
14d0: 74 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79  that the library
14e0: 0a 2a 2a 20 69 73 20 67 75 61 72 61 6e 74 65 65  .** is guarantee
14f0: 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
1500: 66 65 2c 20 6f 6e 6c 79 20 77 68 65 6e 20 69 74  fe, only when it
1510: 20 69 73 20 67 75 61 72 61 6e 74 65 65 64 20 6e   is guaranteed n
1520: 6f 74 0a 2a 2a 20 74 6f 20 62 65 2e 0a 2a 2f 0a  ot.** to be..*/.
1530: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
1540: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
1550: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1560: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1570: 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32 30 30  on Handle {F1200
1580: 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  0}.**.** Each op
1590: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
15a0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
15b0: 64 20 62 79 20 70 6f 69 6e 74 65 72 20 74 6f 20  d by pointer to 
15c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15d0: 68 65 0a 2a 2a 20 6f 70 61 71 75 65 20 73 74 72  he.** opaque str
15e0: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
15f0: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
1600: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
1610: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
1620: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
1630: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
1640: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1650: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1660: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1670: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1680: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
1690: 6f 6e 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61  onstructors.** a
16a0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
16b0: 65 28 29 5d 20 69 73 20 69 74 73 20 64 65 73 74  e()] is its dest
16c0: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61  ructor.  There a
16d0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e  re many other in
16e0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 28 73 75 63  terfaces.** (suc
16f0: 68 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  h as [sqlite3_pr
1700: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
1710: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1720: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
1730: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1740: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
1750: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
1760: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
1770: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e   this.** object.
1780: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1790: 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74  ct sqlite3 sqlit
17a0: 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e3;.../*.** CAPI
17b0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
17c0: 65 67 65 72 20 54 79 70 65 73 20 7b 46 31 30 32  eger Types {F102
17d0: 30 30 7d 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  00}.**.** Becaus
17e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
17f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
1800: 20 74 6f 20 73 70 65 63 69 66 79 20 73 75 63 68   to specify such
1810: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
1820: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
1830: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
1840: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
1850: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 20 7b  d integers..** {
1860: 46 31 30 32 30 31 7d 20 54 68 65 20 73 71 6c 69  F10201} The sqli
1870: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
1880: 69 74 65 33 5f 69 6e 74 36 34 20 74 79 70 65 73  ite3_int64 types
1890: 20 73 70 65 63 69 66 79 20 61 0a 2a 2a 20 36 34   specify a.** 64
18a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
18b0: 67 65 72 2e 20 7b 46 31 30 32 30 32 7d 20 54 68  ger. {F10202} Th
18c0: 65 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  e sqlite_uint64 
18d0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
18e0: 69 6e 74 36 34 20 74 79 70 65 73 20 73 70 65 63  int64 types spec
18f0: 69 66 79 20 61 20 36 34 2d 62 69 74 20 75 6e 73  ify a 64-bit uns
1900: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 20 7b  igned integer. {
1910: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  END}.**.** The s
1920: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
1930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
1940: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
1950: 64 20 74 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69  d type.** defini
1960: 74 69 6f 6e 73 2e 20 20 54 68 65 20 73 71 6c 69  tions.  The sqli
1970: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
1980: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
1990: 20 61 72 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65   are.** supporte
19a0: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
19b0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
19c0: 6c 79 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ly..*/.#ifdef SQ
19d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
19e0: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
19f0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
1a00: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1a10: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
1a20: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
1a30: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1a40: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
1a50: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
1a60: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
1a70: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
1a80: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1a90: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1aa0: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
1ab0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
1ac0: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
1ad0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
1ae0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1af0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
1b00: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
1b10: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
1b20: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
1b30: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
1b40: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
1b50: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
1b60: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
1b70: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
1b80: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
1b90: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
1ba0: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
1bb0: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
1bc0: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
1bd0: 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20  point.*/.#ifdef 
1be0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
1bf0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
1c00: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
1c10: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
1c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c30: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
1c40: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b  ase Connection {
1c50: 46 31 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12010}.**.** {F
1c60: 31 32 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74  12011} The sqlit
1c70: 65 33 5f 63 6c 6f 73 65 28 29 20 69 6e 74 65 72  e3_close() inter
1c80: 66 61 63 65 73 20 64 65 73 74 72 6f 79 73 20 61  faces destroys a
1c90: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
1ca0: 63 74 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ct.** allocated 
1cb0: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
1cc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1cd0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ce0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
1cf0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1d00: 29 5d 2e 20 7b 46 31 32 30 31 32 7d 20 53 71 6c  )]. {F12012} Sql
1d10: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 6c  ite3_close() rel
1d20: 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 6d 65 6d  eases all.** mem
1d30: 6f 72 79 20 75 73 65 64 20 62 79 20 74 68 65 20  ory used by the 
1d40: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63  connection and c
1d50: 6c 6f 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66  loses all open f
1d60: 69 6c 65 73 2e 20 7b 45 4e 44 7d 2e 0a 2a 2a 0a  iles. {END}..**.
1d70: 2a 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74  ** {F12013} If t
1d80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1d90: 65 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a  ection contains.
1da0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
1db0: 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
1dc0: 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61 76  ements] that hav
1dd0: 65 20 6e 6f 74 20 62 65 65 6e 20 66 69 6e 61 6c  e not been final
1de0: 69 7a 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  ized.** by [sqli
1df0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
1e00: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c   then sqlite3_cl
1e10: 6f 73 65 28 29 20 72 65 74 75 72 6e 73 20 53 51  ose() returns SQ
1e20: 4c 49 54 45 5f 42 55 53 59 0a 2a 2a 20 61 6e 64  LITE_BUSY.** and
1e30: 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e   leaves the conn
1e40: 65 63 74 69 6f 6e 20 6f 70 65 6e 2e 20 20 7b 46  ection open.  {F
1e50: 31 32 30 31 34 7d 20 47 69 76 69 6e 67 20 73 71  12014} Giving sq
1e60: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
1e70: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e80: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
1e90: 2d 6f 70 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  -op. {END}.**.**
1ea0: 20 7b 55 31 32 30 31 35 7d 20 50 61 73 73 69 6e   {U12015} Passin
1eb0: 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  g this routine a
1ec0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ed0: 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 61 6c  tion that has al
1ee0: 72 65 61 64 79 20 62 65 65 6e 0a 2a 2a 20 63 6c  ready been.** cl
1ef0: 6f 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e 20  osed results in 
1f00: 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1f10: 6f 72 2e 20 7b 55 31 32 30 31 36 7d 20 49 66 20  or. {U12016} If 
1f20: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
1f30: 20 74 68 61 74 0a 2a 2a 20 72 65 66 65 72 65 6e   that.** referen
1f40: 63 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  ce the same data
1f50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1f60: 61 72 65 20 70 65 6e 64 69 6e 67 20 28 65 69 74  are pending (eit
1f70: 68 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 73 61  her in the.** sa
1f80: 6d 65 20 74 68 72 65 61 64 20 6f 72 20 69 6e 20  me thread or in 
1f90: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
1fa0: 73 29 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  s) when this rou
1fb0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 0a  tine is called,.
1fc0: 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1fd0: 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1fe0: 64 20 61 6e 64 20 69 73 20 61 6c 6d 6f 73 74 20  d and is almost 
1ff0: 63 65 72 74 61 69 6e 6c 79 20 75 6e 64 65 73 69  certainly undesi
2000: 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  rable..*/.int sq
2010: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
2020: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
2030: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
2040: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
2050: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
2060: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
2070: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
2080: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
2090: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
20a0: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
20b0: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
20c0: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
20d0: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
20e0: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
20f0: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
2100: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
2110: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
2120: 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 46 31 32  n Interface {F12
2130: 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  100}.**.** {F121
2140: 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
2150: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2160: 20 65 76 61 6c 75 61 74 65 73 20 7a 65 72 6f 20   evaluates zero 
2170: 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20 55 54 46 2d  or more .** UTF-
2180: 38 20 65 6e 63 6f 64 65 64 2c 20 73 65 6d 69 63  8 encoded, semic
2190: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
21a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
21b0: 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
21c0: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ated.** string o
21d0: 66 20 69 74 73 20 73 65 63 6f 6e 64 20 61 72 67  f its second arg
21e0: 75 6d 65 6e 74 2e 20 20 7b 46 31 32 31 30 32 7d  ument.  {F12102}
21f0: 20 54 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   The SQL.** stat
2200: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2210: 61 74 65 64 20 69 6e 20 74 68 65 20 63 6f 6e 74  ated in the cont
2220: 65 78 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ext of the datab
2230: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
2240: 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 69  * specified by i
2250: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
2260: 6d 65 6e 74 2e 0a 2a 2a 20 7b 46 31 32 31 30 33  ment..** {F12103
2270: 7d 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  } SQL statements
2280: 20 61 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e   are prepared on
2290: 65 20 62 79 20 6f 6e 65 20 75 73 69 6e 67 0a 2a  e by one using.*
22a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
22b0: 72 65 28 29 5d 20 6f 72 20 74 68 65 20 65 71 75  re()] or the equ
22c0: 69 76 61 6c 65 6e 74 2c 20 65 76 61 6c 75 61 74  ivalent, evaluat
22d0: 65 64 0a 2a 2a 20 75 73 69 6e 67 20 6f 6e 65 20  ed.** using one 
22e0: 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
22f0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2300: 5d 2c 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65  ], then destroye
2310: 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2320: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2330: 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20 72 65   {F12104} The re
2340: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  turn value of.**
2350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2360: 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  is SQLITE_OK if 
2370: 61 6c 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  all SQL statemen
2380: 74 20 72 75 6e 0a 2a 2a 20 73 75 63 63 65 73 73  t run.** success
2390: 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fully..**.** {F1
23a0: 32 31 30 35 7d 20 49 66 20 6f 6e 65 20 6f 72 20  2105} If one or 
23b0: 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20  more of the SQL 
23c0: 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65  statements hande
23d0: 64 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d to.** sqlite3_
23e0: 65 78 65 63 28 29 20 61 72 65 20 71 75 65 72 69  exec() are queri
23f0: 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  es, then.** the 
2400: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2410: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
2420: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2430: 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f   is.** invoked o
2440: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2450: 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 72 65   of the query re
2460: 73 75 6c 74 2e 20 7b 46 31 32 31 30 36 7d 0a 2a  sult. {F12106}.*
2470: 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
2480: 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  k returns a non-
2490: 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20  zero value then 
24a0: 74 68 65 20 71 75 65 72 79 0a 2a 2a 20 69 73 20  the query.** is 
24b0: 61 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62  aborted, all sub
24c0: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
24d0: 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b  ements.** are sk
24e0: 69 70 70 65 64 20 61 6e 64 20 74 68 65 20 73 71  ipped and the sq
24f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e  lite3_exec() fun
2500: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
2510: 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
2520: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d  ..**.** {F12107}
2530: 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
2540: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
2550: 65 63 28 29 20 69 73 20 61 6e 20 61 72 62 69 74  ec() is an arbit
2560: 72 61 72 79 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  rary pointer.** 
2570: 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74  that is passed t
2580: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
2590: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
25a0: 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
25b0: 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ameter..**.** {F
25c0: 31 32 31 30 38 7d 20 54 68 65 20 32 6e 64 20 70  12108} The 2nd p
25d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
25e0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
25f0: 6e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  n is the number 
2600: 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e  of.** columns in
2610: 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c   the query resul
2620: 74 2e 20 20 7b 46 31 32 31 30 39 7d 20 54 68 65  t.  {F12109} The
2630: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2640: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  o the callback.*
2650: 2a 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  * is an array of
2660: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
2670: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
2680: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
2690: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78   column.** as ex
26a0: 74 72 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73  tracted using [s
26b0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26c0: 78 74 28 29 5d 2e 20 20 4e 55 4c 4c 20 76 61 6c  xt()].  NULL val
26d0: 75 65 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  ues in the resul
26e0: 74 0a 2a 2a 20 73 65 74 20 72 65 73 75 6c 74 20  t.** set result 
26f0: 69 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  in a NULL pointe
2700: 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  r.  All other va
2710: 6c 75 65 20 61 72 65 20 69 6e 20 74 68 65 69 72  lue are in their
2720: 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
2730: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e   representation.
2740: 20 7b 46 31 32 31 31 37 7d 0a 2a 2a 20 54 68 65   {F12117}.** The
2750: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2760: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
2770: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74  s an array of st
2780: 72 69 6e 67 73 0a 2a 2a 20 6f 62 74 61 69 6e 65  rings.** obtaine
2790: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
27a0: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20  _column_name()] 
27b0: 61 6e 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74  and holding.** t
27c0: 68 65 20 6e 61 6d 65 73 20 6f 66 20 65 61 63 68  he names of each
27d0: 20 63 6f 6c 75 6d 6e 2c 20 61 6c 73 6f 20 69 6e   column, also in
27e0: 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
27f0: 31 32 31 31 30 7d 20 54 68 65 20 63 61 6c 6c 62  12110} The callb
2800: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2810: 20 62 65 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66   be NULL, even f
2820: 6f 72 20 71 75 65 72 69 65 73 2e 20 20 41 20 4e  or queries.  A N
2830: 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ULL.** callback 
2840: 69 73 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e  is not an error.
2850: 20 20 49 74 20 6a 75 73 74 20 6d 65 61 6e 73 20    It just means 
2860: 74 68 61 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b  that no callback
2870: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  .** will be invo
2880: 6b 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ked. .**.** {F12
2890: 31 31 32 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  112} If an error
28a0: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61   occurs while pa
28b0: 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74  rsing or evaluat
28c0: 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74  ing the SQL.** t
28d0: 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61  hen an appropria
28e0: 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
28f0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
2900: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2910: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2920: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
2930: 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64 65 20  *errmsg is made 
2940: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74  to point to that
2950: 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 73 73 75   message.** assu
2960: 6d 69 6e 67 20 65 72 72 6d 73 67 20 69 73 20 6e  ming errmsg is n
2970: 6f 74 20 4e 55 4c 4c 2e 20 20 0a 2a 2a 20 7b 55  ot NULL.  .** {U
2980: 31 32 31 31 33 7d 20 54 68 65 20 63 61 6c 6c 69  12113} The calli
2990: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ng function is r
29a0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
29b0: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
29c0: 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
29d0: 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
29e0: 7b 46 31 32 31 31 36 7d 20 49 66 20 5b 73 71 6c  {F12116} If [sql
29f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
2a00: 61 69 6c 73 20 77 68 69 6c 65 20 61 74 74 65 6d  ails while attem
2a10: 70 74 69 6e 67 20 74 6f 20 67 65 6e 65 72 61 74  pting to generat
2a20: 65 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  e.** the error m
2a30: 65 73 73 61 67 65 2c 20 2a 65 72 72 6d 73 67 20  essage, *errmsg 
2a40: 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2a50: 2a 2a 20 7b 46 31 32 31 31 34 7d 20 49 66 20 65  ** {F12114} If e
2a60: 72 72 6d 73 67 20 69 73 20 4e 55 4c 4c 20 74 68  rrmsg is NULL th
2a70: 65 6e 20 6e 6f 20 61 74 74 65 6d 70 74 20 69 73  en no attempt is
2a80: 20 6d 61 64 65 20 74 6f 20 67 65 6e 65 72 61 74   made to generat
2a90: 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6d 65  e an.** error me
2aa0: 73 73 61 67 65 2e 20 3c 74 6f 64 6f 3e 49 73 20  ssage. <todo>Is 
2ab0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
2ac0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 6f 72 20  SQLITE_NOMEM or 
2ad0: 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
2ae0: 65 72 72 6f 72 20 63 6f 64 65 3f 3c 2f 74 6f 64  error code?</tod
2af0: 6f 3e 20 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61  o> <todo>What ha
2b00: 70 70 65 6e 73 20 69 66 20 74 68 65 72 65 20 61  ppens if there a
2b10: 72 65 20 6d 75 6c 74 69 70 6c 65 20 65 72 72 6f  re multiple erro
2b20: 72 73 3f 0a 2a 2a 20 44 6f 20 77 65 20 67 65 74  rs?.** Do we get
2b30: 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 66 69   code for the fi
2b40: 72 73 74 20 65 72 72 6f 72 2c 20 6f 72 20 69 73  rst error, or is
2b50: 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 72   the choice of r
2b60: 65 70 6f 72 74 65 64 0a 2a 2a 20 65 72 72 6f 72  eported.** error
2b70: 20 61 72 62 69 74 72 61 72 79 3f 3c 2f 74 6f 64   arbitrary?</tod
2b80: 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 35  o>.**.** {F12115
2b90: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
2ba0: 75 65 20 69 73 20 69 73 20 53 51 4c 49 54 45 5f  ue is is SQLITE_
2bb0: 4f 4b 20 69 66 20 74 68 65 72 65 20 61 72 65 20  OK if there are 
2bc0: 6e 6f 20 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a  no errors and.**
2bd0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c   some other [SQL
2be0: 49 54 45 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20  ITE_OK | return 
2bf0: 63 6f 64 65 5d 20 69 66 20 74 68 65 72 65 20 69  code] if there i
2c00: 73 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a  s an error.  .**
2c10: 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   The particular 
2c20: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 64 65 70  return value dep
2c30: 65 6e 64 73 20 6f 6e 20 74 68 65 20 74 79 70 65  ends on the type
2c40: 20 6f 66 20 65 72 72 6f 72 2e 20 20 7b 45 4e 44   of error.  {END
2c50: 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  }.*/.int sqlite3
2c60: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
2c70: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
2c80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c90: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
2ca0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
2cb0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
2cc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2cd0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
2ce0: 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20 2a 2f  o be evaluted */
2cf0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
2d00: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2d10: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
2d20: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
2d30: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
2d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d60: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
2d70: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
2d80: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
2d90: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
2da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2db0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
2dc0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
2dd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2de0: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31  Result Codes {F1
2df0: 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0210}.** KEYWORD
2e00: 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 0a  S: SQLITE_OK.**.
2e10: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
2e20: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2e30: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
2e40: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
2e50: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61 62 6f  set shown.** abo
2e60: 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69  ve in order to i
2e70: 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73  ndicates success
2e80: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
2e90: 2a 2a 20 7b 46 31 30 32 31 31 7d 20 54 68 65 20  ** {F10211} The 
2ea0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
2eb0: 77 6e 20 68 65 72 65 20 61 72 65 20 74 68 65 20  wn here are the 
2ec0: 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74 75 72 6e  only ones return
2ed0: 65 64 20 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65  ed .** by SQLite
2ee0: 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   in its default 
2ef0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e 20 7b  configuration. {
2f00: 46 31 30 32 31 32 7d 20 48 6f 77 65 76 65 72 2c  F10212} However,
2f10: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2f20: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
2f30: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 20 63 61  _codes()] API ca
2f40: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74  n be used to set
2f50: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
2f60: 6f 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72 65 74  onnectoin to ret
2f70: 75 72 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  urn more detaile
2f80: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 2e 20  d result codes. 
2f90: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20  {END}.**.** See 
2fa0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
2fb0: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
2fc0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2fd0: 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ].**.*/.#define 
2fe0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
2ff0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
3000: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
3010: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
3020: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3040: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3050: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3060: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3080: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3090: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
30a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
30b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
30c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
30d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
30e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
30f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3100: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
3110: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
3120: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
3130: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
3140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3150: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
3160: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3170: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
3180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3190: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
31a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
31b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
31c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
31d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
31e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
31f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
3200: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3210: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
3220: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
3230: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
3240: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
3250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
3260: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
3270: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
3280: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
3290: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
32a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
32b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
32c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
32d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
32e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
32f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
3300: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
3310: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
3320: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
3330: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3340: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
3350: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
3360: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
3370: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
3380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
3390: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
33a0: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
33b0: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
33c0: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
33d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
33e0: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
33f0: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
3400: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
3410: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3420: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
3430: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
3440: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
3450: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
3460: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3470: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
3480: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
3490: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
34a0: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
34b0: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
34c0: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
34d0: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
34e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
34f0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
3500: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
3510: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
3520: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3530: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
3540: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
3550: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
3560: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
3570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
3580: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
3590: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
35a0: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
35b0: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
35c0: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
35d0: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
35e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
35f0: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
3600: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
3610: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
3620: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
3630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3640: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
3650: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
3660: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
3670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
3680: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
3690: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
36a0: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
36b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36c0: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
36d0: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
36e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
36f0: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
3700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3710: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
3720: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
3730: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
3740: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
3750: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3760: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
3770: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
3780: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
3790: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
37a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
37b0: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
37c0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
37d0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
37e0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
37f0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3800: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
3810: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
3820: 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32 30  lt Codes {F10220
3830: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
3840: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
3850: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
3860: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
3870: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
3880: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
3890: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
38a0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
38b0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
38c0: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
38d0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
38e0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
38f0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
3900: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
3910: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
3920: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
3930: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
3940: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
3950: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
3960: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
3970: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
3980: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
3990: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
39a0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
39b0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
39c0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
39d0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
39e0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
39f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
3a00: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 7b 46  about errors. {F
3a10: 31 30 32 32 31 7d 20 54 68 65 20 65 78 74 65 6e  10221} The exten
3a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
3a30: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
3a40: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20  disabled.** for 
3a50: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
3a60: 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74  nnection using t
3a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
3a80: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
3a90: 73 28 29 5d 0a 2a 2a 20 41 50 49 2e 20 7b 45 4e  s()].** API. {EN
3aa0: 44 7d 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f  D}.** .** Some o
3ab0: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
3ac0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3ad0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
3ae0: 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78   above..** We ex
3af0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3b00: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3b10: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3b20: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b30: 74 69 6d 65 2e 20 20 7b 55 31 30 34 32 32 7d 20  time.  {U10422} 
3b40: 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73  Software that us
3b50: 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  es extended resu
3b60: 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20  lt codes should 
3b70: 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65  expect.** to see
3b80: 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65   new result code
3b90: 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
3ba0: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
3bb0: 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  {END}.** .** {F1
3bc0: 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c  0223} The symbol
3bd0: 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65  ic name for an e
3be0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3bf0: 6f 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61  ode always conta
3c00: 69 6e 73 0a 2a 2a 20 61 20 72 65 6c 61 74 65 64  ins.** a related
3c10: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
3c20: 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78  code as a prefix
3c30: 2e 20 7b 46 31 30 32 32 34 7d 20 50 72 69 6d 61  . {F10224} Prima
3c40: 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ry result.** cod
3c50: 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  es contain a sin
3c60: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
3c70: 72 2e 20 20 7b 46 31 30 32 32 35 7d 20 45 78 74  r.  {F10225} Ext
3c80: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3c90: 65 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74 77  es.** contain tw
3ca0: 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68  o or more "_" ch
3cb0: 61 72 61 63 74 65 72 73 2e 20 7b 46 31 30 32 32  aracters. {F1022
3cc0: 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76  6} The numeric v
3cd0: 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 65 78  alue of an.** ex
3ce0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3cf0: 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76 65 72  de can be conver
3d00: 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20 63 6f  ted to its.** co
3d10: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d  rresponding prim
3d20: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
3d30: 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66 20 74  by masking off t
3d40: 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74 65 73  he lower 8 bytes
3d50: 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
3d60: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
3d70: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
3d80: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
3d90: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
3da0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
3db0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
3dc0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
3dd0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3de0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
3df0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3e00: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
3e10: 44 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  D    (SQLITE_IOE
3e20: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
3e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e40: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
3e50: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3e60: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
3e70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
3e80: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
3e90: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
3ea0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3eb0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
3ec0: 43 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f  C     (SQLITE_IO
3ed0: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
3ee0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3ef0: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
3f00: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3f10: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
3f20: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
3f30: 54 41 54 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAT         (SQL
3f40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
3f50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3f60: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
3f70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3f80: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
3f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3fa0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
3fb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3fc0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
3fd0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
3fe0: 45 4c 45 54 45 20 20 20 20 20 20 20 20 28 53 51  ELETE        (SQ
3ff0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
4000: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4010: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
4020: 45 44 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  ED       (SQLITE
4030: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
4040: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4050: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
4060: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4070: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 0a 2f  RR | (12<<8))../
4080: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4090: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
40a0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46  en Operations {F
40b0: 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  10230}.**.** {F1
40c0: 30 32 33 31 7d 20 53 6f 6d 65 20 63 6f 6d 62 69  0231} Some combi
40d0: 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 74 68  nation of the th
40e0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
40f0: 72 65 20 75 73 65 64 20 61 73 20 74 68 65 0a 2a  re used as the.*
4100: 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
4110: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
4120: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
4130: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20  rface and.** as 
4140: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
4150: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
4160: 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  hod of the.** [s
4170: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
4180: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
4190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
41a0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
41b0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
41c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
41d0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
41e0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
41f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
4200: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
4210: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
4230: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
4240: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
4260: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
4270: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4280: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
4290: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
42a0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
42b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
42c0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
42d0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
42e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
42f0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
4300: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
4310: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
4320: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
4330: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
4340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
4350: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
4360: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
4370: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
4380: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
4390: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
43a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
43b0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
43c0: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
43d0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
43e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b  haracteristics {
43f0: 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F10240}.**.** {F
4400: 31 30 32 34 31 7d 20 54 68 65 20 78 44 65 76 69  10241} The xDevi
4410: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d  ceCapabilities m
4420: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
4430: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4440: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
4450: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
4460: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
4470: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
4480: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
4490: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
44a0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
44b0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
44c0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
44d0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
44e0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
44f0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
4500: 66 65 72 73 20 74 6f 2e 20 7b 45 4e 44 7d 0a 2a  fers to. {END}.*
4510: 2a 0a 2a 2a 20 7b 46 31 30 32 34 32 7d 20 54 68  *.** {F10242} Th
4520: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
4530: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
4540: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
4550: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
4560: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
4570: 20 7b 46 31 30 32 34 33 7d 20 54 68 65 20 53 51   {F10243} The SQ
4580: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4590: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
45a0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
45b0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
45c0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
45d0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
45e0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
45f0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
4600: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
4610: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
4620: 20 61 74 6f 6d 69 63 2e 20 20 7b 46 31 30 32 34   atomic.  {F1024
4630: 34 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  4} The SQLITE_IO
4640: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
4650: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
4660: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
4670: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
4680: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
4690: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
46a0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
46b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
46c0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
46d0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
46e0: 20 61 72 6f 75 6e 64 2e 20 20 7b 46 31 30 32 34   around.  {F1024
46f0: 35 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  5} The SQLITE_IO
4700: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
4710: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
4720: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
4730: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
4740: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
4750: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
4760: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
4770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4780: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
4790: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
47a0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
47b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
47c0: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  2       0x000000
47d0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
47e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
47f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4800: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
4810: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
4820: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4830: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
4840: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
4850: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4860: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
4870: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
4880: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4890: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
48a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
48b0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
48c0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
48d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
48e0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
48f0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
4900: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
4910: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31  K       0x000001
4920: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4930: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4940: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32  END     0x000002
4950: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4970: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34  AL      0x000004
4980: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
4990: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
49a0: 20 4c 65 76 65 6c 73 20 7b 46 31 30 32 35 30 7d   Levels {F10250}
49b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 35 31 7d 20  .**.** {F10251} 
49c0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
49d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
49e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
49f0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
4a00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
4a10: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
4a20: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
4a30: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
4a40: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
4a50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
4a60: 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a  bject. {END}.*/.
4a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4a80: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
4a90: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
4aa0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
4ab0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
4ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
4ad0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
4ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4af0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4b10: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
4b20: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
4b30: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
4b40: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
4b50: 7b 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F10260}.**.** {
4b60: 46 31 30 32 36 31 7d 20 57 68 65 6e 20 53 51 4c  F10261} When SQL
4b70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
4b80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
4b90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
4ba0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4bb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
4bc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65  mbination of the
4bd0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
4be0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
4bf0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
4c00: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 32 7d 20  .**.** {F10262} 
4c10: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
4c20: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
4c30: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
4c40: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
4c50: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
4c60: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
4c70: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
4c80: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
4c90: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
4ca0: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
4cb0: 68 65 64 2e 20 7b 46 31 30 32 36 33 7d 20 54 68  hed. {F10263} Th
4cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
4cd0: 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a 20 74  RMAL means .** t
4ce0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
4cf0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20  nc() semantics. 
4d00: 7b 46 31 30 32 36 34 7d 20 54 68 65 20 53 51 4c  {F10264} The SQL
4d10: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
4d20: 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20  ag means .** to 
4d30: 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  use Mac OS-X sty
4d40: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
4d50: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
4d60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4d70: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
4d80: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4da0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
4db0: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
4dc0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
4dd0: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
4de0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
4df0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
4e00: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
4e10: 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F11110}.**.** 
4e20: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
4e30: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
4e40: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
4e50: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e   in the OS.** in
4e60: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20  terface layer.  
4e70: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
4e80: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e  terface implemen
4e90: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
4ea0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
4eb0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
4ec0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
4ed0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
4ee0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
4ef0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
4f00: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
4f10: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
4f20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4f30: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
4f40: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
4f50: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
4f60: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
4f70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
4f80: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
4f90: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
4fa0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
4fb0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
4fc0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
4fd0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
4fe0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
4ff0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
5000: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
5010: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
5020: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
5030: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
5040: 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 46 31  thods Object {F1
5050: 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72  1120}.**.** Ever
5060: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
5070: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
5080: 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  s] xOpen method 
5090: 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74  contains a point
50a0: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74  er to.** an inst
50b0: 61 6e 63 65 20 6f 66 20 74 68 65 20 74 68 69 73  ance of the this
50c0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
50d0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
50e0: 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65  e.** methods use
50f0: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
5100: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20  ious operations 
5110: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
5120: 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   file..**.** The
5130: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
5140: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
5150: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
5160: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
5170: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
5180: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
5190: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
51a0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
51b0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f    The second cho
51c0: 69 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d  ice is an.** OS-
51d0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
51e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  .  The SQLITE_SY
51f0: 4e 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79  NC_DATA flag may
5200: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a   be ORed in to.*
5210: 2a 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  * indicate that 
5220: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
5230: 20 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f   the file and no
5240: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
5250: 73 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65  s to be.** synce
5260: 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e  d..** .** The in
5270: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
5280: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5290: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
52a0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
52b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
52c0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
52d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
52e0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
52f0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5300: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5310: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
5320: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
5330: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
5340: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
5350: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
5360: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
5370: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
5380: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  s the lock.  .**
5390: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
53a0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
53b0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65   looks.** to see
53c0: 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65   if any database
53d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74   connection, eit
53e0: 68 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70  her in this.** p
53f0: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
5400: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
5410: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52   is holding an R
5420: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
5430: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
5440: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
5450: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
5460: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
5470: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
5480: 64 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a  d false if not..
5490: 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  ** .** The xFile
54a0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
54b0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
54c0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
54d0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
54e0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
54f0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
5500: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
5510: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
5520: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
5530: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
5540: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
5550: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  "op" argument.**
5560: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   is an integer o
5570: 70 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69  pcode.   The thi
5580: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  rd.** argument i
5590: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
55a0: 74 65 72 20 77 68 69 63 68 20 69 73 20 69 6e 74  ter which is int
55b0: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f  ended to be a po
55c0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74  inter.** to a st
55d0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
55e0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
55f0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
5600: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
5610: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
5620: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
5630: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
5640: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
5650: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
5660: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
5670: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
5680: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
5690: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
56a0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
56b0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
56c0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
56d0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
56e0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
56f0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
5700: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
5710: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
5720: 65 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20  eserves opcodes 
5730: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
5740: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a  r its own use. .
5750: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
5760: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
5770: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
5780: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
5790: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
57a0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
57b0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
57c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
57d0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
57e0: 6f 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61  opcodes .** grea
57f0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
5800: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
5810: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
5820: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
5830: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
5840: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
5850: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
5860: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
5870: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
5880: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
5890: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
58a0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
58b0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
58c0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
58d0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
58e0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
58f0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
5900: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
5910: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
5920: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
5930: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
5940: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
5950: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
5960: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5970: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
5980: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
5990: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
59a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
59b0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
59c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
59d0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
59e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
59f0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
5a00: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5a10: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
5a20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5a30: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
5a40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5a50: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
5a60: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5a70: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
5a80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
5a90: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
5aa0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
5ab0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
5ac0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
5ad0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5ae0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
5af0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
5b00: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
5b10: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
5b20: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5b30: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
5b40: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
5b50: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
5b60: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
5b70: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
5b80: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
5b90: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
5ba0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
5bb0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
5bc0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
5bd0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5be0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5bf0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
5c00: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
5c10: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
5c20: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
5c30: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
5c40: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
5c50: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
5c60: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
5c70: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
5c80: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
5c90: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5ca0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
5cb0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
5cc0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
5cd0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
5ce0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
5cf0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
5d00: 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  ite()..*/.typede
5d10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
5d30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
5d40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
5d50: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
5d60: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
5d70: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
5d80: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
5d90: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
5da0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
5db0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
5dc0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
5dd0: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
5de0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5df0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
5e00: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
5e10: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
5e20: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
5e30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
5e40: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
5e50: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
5e60: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
5e70: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
5e80: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
5e90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5ea0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
5eb0: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
5ec0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
5ed0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
5ee0: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
5ef0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
5f00: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
5f10: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
5f20: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
5f30: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
5f40: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
5f50: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
5f60: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
5f70: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
5f80: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
5f90: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
5fa0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
5fb0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
5fc0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
5fd0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
5fe0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
5ff0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
6000: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
6010: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
6020: 20 4f 70 63 6f 64 65 73 20 7b 46 31 31 33 31 30   Opcodes {F11310
6030: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
6040: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
6050: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
6060: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
6070: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
6080: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6090: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
60a0: 64 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  d to the [sqlite
60b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
60c0: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
60d0: 2a 2a 0a 2a 2a 20 7b 46 31 31 33 31 31 7d 20 54  **.** {F11311} T
60e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
60f0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
6100: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
6110: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
6120: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 73 65 73 20  ** opcode cases 
6130: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
6140: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
6150: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
6160: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
6170: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
6180: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
6190: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
61a0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
61b0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
61c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
61d0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
61e0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
61f0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
6200: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
6210: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
6220: 74 73 20 74 6f 2e 20 7b 46 31 31 33 31 32 7d 20  ts to. {F11312} 
6230: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
6240: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
6250: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
6260: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
6270: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
6280: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
6290: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66  defined..*/.#def
62a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
62b0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
62c0: 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    1../*.** CAPI3
62d0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
62e0: 65 20 7b 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a  e {F17110}.**.**
62f0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
6300: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
6310: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
6320: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
6330: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
6340: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
6350: 6a 65 63 74 2e 20 20 7b 46 31 37 31 31 31 7d 20  ject.  {F17111} 
6360: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
6370: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
6380: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
6390: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
63a0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
63b0: 65 78 5d 2e 20 7b 45 4e 44 7d 20 49 74 20 6f 6e  ex]. {END} It on
63c0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
63d0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
63e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
63f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
6400: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
6410: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
6420: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
6430: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
6440: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
6450: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
6460: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6470: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
6480: 62 6a 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a  bject {F11140}.*
6490: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
64a0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
64b0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
64c0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 74 68  rface between th
64d0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65  e.** SQLite core
64e0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
64f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6500: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6510: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6520: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6530: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6540: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
6550: 2a 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69  **.** The iVersi
6560: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
6570: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
6580: 62 65 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75  be larger for fu
6590: 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
65a0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
65b0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
65c0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
65d0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
65e0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
65f0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
6600: 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
6610: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
6620: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
6630: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
6640: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
6650: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
6660: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
6670: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
6680: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
6690: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
66a0: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
66b0: 2a 20 52 65 67 69 73 74 65 72 65 64 20 76 66 73  * Registered vfs
66c0: 20 6d 6f 64 75 6c 65 73 20 61 72 65 20 6b 65 70   modules are kep
66d0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
66e0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
66f0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
6700: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
6710: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
6720: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
6730: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
6740: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
6750: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
6760: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
6770: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
6780: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
6790: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
67a0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
67b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
67c0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
67d0: 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68  nly fields in th
67e0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a  e sqlite3_vfs .*
67f0: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
6800: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
6810: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
6820: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
6830: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
6840: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
6850: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
6860: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
6870: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
6880: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
6890: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
68a0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
68b0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
68c0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
68d0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
68e0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
68f0: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
6900: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
6910: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
6920: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
6930: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
6940: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
6950: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ules..**.** {F11
6960: 31 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  141} SQLite will
6970: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
6980: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74  the zFilename st
6990: 72 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a  ring passed to.*
69a0: 2a 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66  * xOpen() is a f
69b0: 75 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20  ull pathname as 
69c0: 67 65 6e 65 72 61 74 65 64 20 62 79 20 78 46 75  generated by xFu
69d0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64  llPathname() and
69e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74 72  .** that the str
69f0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
6a00: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
6a10: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
6a20: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45  s.** called.  {E
6a30: 4e 44 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69  ND} So the [sqli
6a40: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74  te3_file] can st
6a50: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
6a60: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
6a70: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
6a80: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
6a90: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
6aa0: 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eason..**.** {F1
6ab0: 31 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20  1142} The flags 
6ac0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
6ad0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
6ae0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
6af0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
6b00: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
6b10: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
6b20: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
6b30: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
6b40: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
6b50: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
6b60: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
6b70: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
6b80: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
6b90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
6ba0: 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66  TE]. {END}.** If
6bb0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
6bc0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
6bd0: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
6be0: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
6bf0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
6c00: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
6c10: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
6c20: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a  utFlags may be.*
6c30: 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46  * set..** .** {F
6c40: 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69  11143} SQLite wi
6c50: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
6c60: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
6c70: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
6c80: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
6c90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
6ca0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
6cb0: 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  ned:.** .** <ul>
6cc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
6cd0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
6ce0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
6cf0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6d00: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
6d10: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6d20: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
6d30: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
6d40: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
6d50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
6d60: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
6d70: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
6d80: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
6d90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
6da0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6db0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  L].** </ul> {END
6dc0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  }.**.** The file
6dd0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
6de0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
6df0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
6e00: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20  s to.** changes 
6e10: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
6e20: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
6e30: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
6e40: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
6e50: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
6e60: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
6e70: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
6e80: 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  , might make.** 
6e90: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
6ea0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
6eb0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
6ec0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a  his journal are.
6ed0: 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e  ** also a no-op.
6ee0: 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
6ef0: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
6f00: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
6f10: 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65  IOERR..** Or the
6f20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
6f30: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
6f40: 74 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66  the a database f
6f50: 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64  ile will.** be d
6f60: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
6f70: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
6f80: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
6f90: 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61  andom order.** a
6fa0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
6fb0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
6fc0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20  rdingly..** .** 
6fd0: 7b 46 31 31 31 34 34 7d 20 53 51 4c 69 74 65 20  {F11144} SQLite 
6fe0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
6ff0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
7000: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
7010: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64   xOpen.** method
7020: 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
7030: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
7040: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
7050: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7060: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7070: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ].** </ul>.** .*
7080: 2a 20 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b  * {F11145} The [
7090: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
70a0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
70b0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
70c0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
70d0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
70e0: 6c 6f 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d  losed.  {F11146}
70f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7100: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7110: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
7120: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
7130: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
7140: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
7150: 73 2e 20 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20  s. .** {F11147} 
7160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7170: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
7180: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
7190: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
71a0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
71b0: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
71c0: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
71d0: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
71e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
71f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
7200: 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  {END}.** .** {F1
7210: 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73  1148} At least s
7220: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
7230: 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
7240: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 0a  ated by SQLite .
7250: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
7260: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
7270: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
7280: 61 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a  as the third .**
7290: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
72a0: 65 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20  en.  {END}  The 
72b0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
72c0: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
72d0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
72e0: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
72f0: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
7300: 69 6e 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31  in..** .** {F111
7310: 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  49} The flags ar
7320: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
7330: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
7340: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
7350: 5d 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  ] .** to test fo
7360: 72 20 74 68 65 20 65 78 69 73 74 61 6e 63 65 20  r the existance 
7370: 6f 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72  of a file,.** or
7380: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
7390: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65  READWRITE] to te
73a0: 73 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20  st to see.** if 
73b0: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
73c0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
73d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
73e0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
73f0: 65 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20  est to see if a 
7400: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
7410: 20 72 65 61 64 61 62 6c 65 2e 20 20 7b 45 4e 44   readable.  {END
7420: 7d 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62  } The file can b
7430: 65 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72  e a .** director
7440: 79 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 35  y..** .** {F1115
7450: 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  0} SQLite will a
7460: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
7470: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
7480: 6d 65 2b 31 20 62 79 74 65 20 66 6f 72 0a 2a 2a  me+1 byte for.**
7490: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
74a0: 65 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70  ers for xGetTemp
74b0: 6e 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61  name and xFullPa
74c0: 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31 7d  thname. {F11151}
74d0: 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20 73 69   The exact.** si
74e0: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
74f0: 20 62 75 66 66 65 72 20 69 73 20 61 6c 73 6f 20   buffer is also 
7500: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
7510: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 0a 2a  meter to both .*
7520: 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d  * methods. {END}
7530: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
7540: 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61 72  uffer is not lar
7550: 67 65 20 65 6e 6f 75 67 68 2c 20 53 51 4c 49 54  ge enough, SQLIT
7560: 45 5f 43 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73 68  E_CANTOPEN.** sh
7570: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
7580: 2e 20 41 73 20 74 68 69 73 20 69 73 20 68 61 6e  . As this is han
7590: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
75a0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
75b0: 0a 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  .** vfs implemen
75c0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
75d0: 6e 64 65 61 76 6f 72 20 74 6f 20 70 72 65 76 65  ndeavor to preve
75e0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
75f0: 6e 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61 6d  ng .** mxPathnam
7600: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
7610: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
7620: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 6e  .** .** The xRan
7630: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
7640: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
7650: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
7660: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
7670: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
7680: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
7690: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
76a0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
76b0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
76c0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
76d0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
76e0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
76f0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
7700: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
7710: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
7720: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
7730: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
7740: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
7750: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
7760: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
7770: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
7780: 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65  d.  The.** xSlee
7790: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
77a0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
77b0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
77c0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
77d0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
77e0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
77f0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
7800: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
7810: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
7820: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
7830: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
7840: 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79  d.** time..*/.ty
7850: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7860: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
7870: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  _vfs;.struct sql
7880: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
7890: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
78a0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
78b0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
78c0: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  r */.  int szOsF
78d0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
78e0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
78f0: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
7900: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
7910: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
7920: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
7930: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
7940: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
7950: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
7960: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
7970: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
7980: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
7990: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
79a0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
79b0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
79c0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
79d0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
79e0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
79f0: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
7a00: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
7a10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
7a20: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
7a30: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
7a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
7a50: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
7a60: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
7a70: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
7a80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7a90: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7aa0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
7ab0: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
7ac0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7ad0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7ae0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
7af0: 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28 73  *xGetTempname)(s
7b00: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
7b10: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
7b20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
7b30: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
7b40: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
7b50: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
7b60: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
7b70: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
7b80: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
7b90: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7ba0: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
7bb0: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
7bc0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
7bd0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
7be0: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a  rrMsg);.  void *
7bf0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
7c00: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
7c10: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
7c20: 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  l);.  void (*xDl
7c30: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
7c40: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
7c50: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
7c60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
7c70: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
7c80: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
7c90: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
7ca0: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
7cb0: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
7cc0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
7cd0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
7ce0: 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20  ble*);.  /* New 
7cf0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
7d00: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
7d10: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
7d20: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
7d30: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
7d40: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
7d50: 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a   happens. */.};.
7d60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7d70: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
7d80: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
7d90: 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a  d {F11190}.**.**
7da0: 20 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65 20   {F11191} These 
7db0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
7dc0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
7dd0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
7de0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
7df0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
7e00: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
7e10: 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20  ] object. {END} 
7e20: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
7e30: 2a 2a 20 74 68 65 20 6b 69 6e 64 20 6f 66 20 77  ** the kind of w
7e40: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
7e50: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
7e60: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a  ess method is.**
7e70: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b   looking for.  {
7e80: 46 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c  F11192} With SQL
7e90: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
7ea0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
7eb0: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
7ec0: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66  checks to see if
7ed0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
7ee0: 2e 20 7b 46 31 31 31 39 33 7d 20 57 69 74 68 0a  . {F11193} With.
7ef0: 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ** SQLITE_ACCESS
7f00: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
7f10: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 63  xAccess method c
7f20: 68 65 63 6b 73 20 74 6f 20 73 65 65 0a 2a 2a 20  hecks to see.** 
7f30: 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 62  if the file is b
7f40: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
7f50: 20 77 72 69 74 61 62 6c 65 2e 20 20 7b 46 31 31   writable.  {F11
7f60: 31 39 34 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c  194} With.** SQL
7f70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
7f80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
7f90: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f 20  od.** checks to 
7fa0: 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20  see if the file 
7fb0: 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a  is readable..*/.
7fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7fd0: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
7fe0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7ff0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8000: 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  E 1.#define SQLI
8010: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
8020: 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      2../*.** CAP
8030: 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
8040: 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
8050: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  d Result Codes {
8060: 46 31 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12200}.**.** {F
8070: 31 32 32 30 31 7d 20 54 68 65 20 73 71 6c 69 74  12201} The sqlit
8080: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
8090: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
80a0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
80b0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53  sables the.** [S
80c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
80d0: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
80e0: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
80f0: 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 0a  e on a database.
8100: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 66  ** connection if
8110: 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
8120: 65 72 20 69 73 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  er is.** non-zer
8130: 6f 20 6f 72 20 7a 65 72 6f 2c 20 72 65 73 70 65  o or zero, respe
8140: 63 74 69 76 65 6c 79 2e 20 7b 46 31 32 32 30 32  ctively. {F12202
8150: 7d 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74 2c  }.** By default,
8160: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
8170: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
8180: 6f 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65 67  of only 26 integ
8190: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
81a0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
81b0: 2e 20 20 7b 46 31 32 32 30 33 7d 20 57 68 65 6e  .  {F12203} When
81c0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
81d0: 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e   codes.** are en
81e0: 61 62 6c 65 64 20 62 79 20 74 68 69 73 20 72 6f  abled by this ro
81f0: 75 74 69 6e 65 2c 20 74 68 65 20 72 65 70 65 74  utine, the repet
8200: 6f 69 72 65 20 6f 66 20 72 65 73 75 6c 74 20 63  oire of result c
8210: 6f 64 65 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d  odes can be.** m
8220: 75 63 68 20 6c 61 72 67 65 72 20 61 6e 64 20 63  uch larger and c
8230: 61 6e 20 28 68 6f 70 65 66 75 6c 6c 79 29 20 70  an (hopefully) p
8240: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
8250: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
8260: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 63 61  .** about the ca
8270: 75 73 65 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e  use of an error.
8280: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 34 7d 20  .**.** {F12204} 
8290: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
82a0: 65 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ent is a boolean
82b0: 20 76 61 6c 75 65 20 74 68 61 74 20 74 75 72 6e   value that turn
82c0: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
82d0: 74 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e  t.** codes on an
82e0: 64 20 6f 66 66 2e 20 7b 46 31 32 32 30 35 7d 20  d off. {F12205} 
82f0: 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  Extended result 
8300: 63 6f 64 65 73 20 61 72 65 20 6f 66 66 20 62 79  codes are off by
8310: 20 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a 2a 20   default for.** 
8320: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
8330: 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
8340: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
8350: 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
8360: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
8370: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
8380: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
8390: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
83a0: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
83b0: 6f 77 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a  owid {F12220}.**
83c0: 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20 45 61 63  .** {F12221} Eac
83d0: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
83e0: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
83f0: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
8400: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
8410: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
8420: 22 72 6f 77 69 64 22 2e 20 20 7b 46 31 32 32 32  "rowid".  {F1222
8430: 32 7d 20 54 68 65 20 72 6f 77 69 64 20 69 73 20  2} The rowid is 
8440: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
8450: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
8460: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
8470: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
8480: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
8490: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
84a0: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
84b0: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
84c0: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
84d0: 6d 6e 73 2e 20 7b 46 31 32 32 32 33 7d 20 49 66  mns. {F12223} If
84e0: 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
84f0: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
8500: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
8510: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
8520: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
8530: 6f 74 68 65 72 20 61 6e 20 61 6c 69 61 73 20 66  other an alias f
8540: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
8550: 0a 2a 2a 20 7b 46 31 32 32 32 34 7d 20 54 68 69  .** {F12224} Thi
8560: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
8570: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
8580: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
8590: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  * successful INS
85a0: 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ERT into the dat
85b0: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64  abase from the d
85c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
85d0: 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 74  on.** shown in t
85e0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
85f0: 74 2e 20 20 7b 46 31 32 32 32 35 7d 20 49 66 20  t.  {F12225} If 
8600: 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e  no successful in
8610: 73 65 72 74 73 0a 2a 2a 20 68 61 76 65 20 65 76  serts.** have ev
8620: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
8630: 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
8640: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
8650: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
8660: 20 7b 46 31 32 32 32 36 7d 20 49 66 20 61 6e 20   {F12226} If an 
8670: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69  INSERT occurs wi
8680: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
8690: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
86a0: 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65  f the.** inserte
86b0: 64 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  d row is returne
86c0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
86d0: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
86e0: 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72   trigger.** is r
86f0: 75 6e 6e 69 6e 67 2e 20 20 7b 46 31 32 32 32 37  unning.  {F12227
8700: 7d 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  } But once the t
8710: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
8720: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
8730: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  urned.** by this
8740: 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
8750: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
8760: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
8770: 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65  re the.** trigge
8780: 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  r fired..**.** {
8790: 46 31 32 32 32 38 7d 20 41 6e 20 49 4e 53 45 52  F12228} An INSER
87a0: 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  T that fails due
87b0: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
87c0: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
87d0: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
87e0: 6c 20 69 6e 73 65 72 74 20 61 6e 64 20 64 6f 65  l insert and doe
87f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
8800: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
8810: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
8820: 6e 65 2e 20 20 7b 46 31 32 32 32 39 7d 20 54 68  ne.  {F12229} Th
8830: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
8840: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
8850: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
8860: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
8870: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
8880: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
8890: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
88a0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
88b0: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
88c0: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
88d0: 73 2e 20 20 7b 46 31 32 32 33 31 7d 20 57 68 65  s.  {F12231} Whe
88e0: 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
88f0: 41 43 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  ACE .** encounte
8900: 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
8910: 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
8920: 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
8930: 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
8940: 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
8950: 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
8960: 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
8970: 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
8980: 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
8990: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
89a0: 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
89b0: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
89c0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
89d0: 73 20 69 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a  s interface. .**
89e0: 0a 2a 2a 20 7b 55 46 31 32 32 33 32 7d 20 49 66  .** {UF12232} If
89f0: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
8a00: 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72  does a new inser
8a10: 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
8a20: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8a30: 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20  n.** while this 
8a40: 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
8a50: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
8a60: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
8a70: 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68  ert rowid,.** th
8a80: 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
8a90: 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
8aa0: 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
8ab0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
8ac0: 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
8ad0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
8ae0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
8af0: 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
8b00: 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
8b10: 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32  s Modified {F122
8b20: 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34  40}.**.** {F1224
8b30: 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  1} This function
8b40: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
8b50: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
8b60: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
8b70: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
8b80: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
8b90: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
8ba0: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
8bb0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
8bc0: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
8bd0: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
8be0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
8bf0: 74 65 72 2e 20 7b 46 31 32 32 34 32 7d 20 4f 6e  ter. {F12242} On
8c00: 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  ly.** changes th
8c10: 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
8c20: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
8c30: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
8c40: 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74   or.** DELETE st
8c50: 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
8c60: 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
8c70: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
8c80: 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72  y.** triggers ar
8c90: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 7b  e not counted. {
8ca0: 46 31 32 32 34 33 7d 20 55 73 65 20 74 68 65 20  F12243} Use the 
8cb0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
8cc0: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
8cd0: 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68  on.** to find th
8ce0: 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
8cf0: 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64  f changes includ
8d00: 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
8d10: 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a  ed by triggers..
8d20: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 34 7d 20 57  **.** {F12244} W
8d30: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
8d40: 66 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  f a trigger, the
8d50: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
8d60: 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
8d70: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
8d80: 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
8d90: 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
8da0: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
8db0: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
8dc0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
8dd0: 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
8de0: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
8df0: 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
8e00: 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
8e10: 7b 46 31 32 32 34 35 7d 20 41 6c 6c 20 63 68 61  {F12245} All cha
8e20: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
8e30: 2c 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 61  , even if they a
8e40: 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20  re later undone 
8e50: 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b  by a.** ROLLBACK
8e60: 20 6f 72 20 41 42 4f 52 54 2e 20 20 7b 46 31 32   or ABORT.  {F12
8e70: 32 34 36 7d 20 45 78 63 65 70 74 2c 20 63 68 61  246} Except, cha
8e80: 6e 67 65 73 20 61 73 73 6f 63 69 61 74 65 64 20  nges associated 
8e90: 77 69 74 68 20 63 72 65 61 74 69 6e 67 20 61 6e  with creating an
8ea0: 64 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 20 74 61  d.** dropping ta
8eb0: 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 63 6f 75  bles are not cou
8ec0: 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  nted..**.** {F12
8ed0: 32 34 37 7d 20 49 66 20 61 20 63 61 6c 6c 62 61  247} If a callba
8ee0: 63 6b 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  ck invokes [sqli
8ef0: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
8f00: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 0a  sqlite3_step()].
8f10: 2a 2a 20 72 65 63 75 72 73 69 76 65 6c 79 2c 20  ** recursively, 
8f20: 74 68 65 6e 20 74 68 65 20 63 68 61 6e 67 65 73  then the changes
8f30: 20 69 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20 72   in the inner, r
8f40: 65 63 75 72 73 69 76 65 20 63 61 6c 6c 20 61 72  ecursive call ar
8f50: 65 0a 2a 2a 20 63 6f 75 6e 74 65 64 20 74 6f 67  e.** counted tog
8f60: 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 63  ether with the c
8f70: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6f 75  hanges in the ou
8f80: 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ter call..**.** 
8f90: 7b 46 31 32 32 34 38 7d 20 53 51 4c 69 74 65 20  {F12248} SQLite 
8fa0: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
8fb0: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46  ommand "DELETE F
8fc0: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f  ROM table" witho
8fd0: 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c  ut.** a WHERE cl
8fe0: 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67  ause by dropping
8ff0: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20   and recreating 
9000: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69  the table.  (Thi
9010: 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73  s is much.** fas
9020: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 20 74  ter than going t
9030: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74  hrough and delet
9040: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65  ing individual e
9050: 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65  lements from the
9060: 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42 65 63  .** table.)  Bec
9070: 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f 70 74  ause of this opt
9080: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63  imization, the c
9090: 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20  hange count for 
90a0: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
90b0: 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 20   table" will be 
90c0: 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20  zero regardless 
90d0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
90e0: 20 65 6c 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61   elements.** tha
90f0: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
9100: 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20  y in the table. 
9110: 7b 46 31 32 32 35 31 7d 20 54 6f 20 67 65 74 20  {F12251} To get 
9120: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
9130: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 75 6d 62  t.** of the numb
9140: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
9150: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
9160: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
9170: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
9180: 2a 2a 0a 2a 2a 20 7b 55 46 31 32 32 35 32 7d 20  **.** {UF12252} 
9190: 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
91a0: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
91b0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
91c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
91d0: 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  ** while this ro
91e0: 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
91f0: 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
9200: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
9210: 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64  outine.** is und
9220: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
9230: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
9240: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
9250: 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
9260: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
9270: 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 36 30  Modified {F12260
9280: 7d 0a 2a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 31  }.***.** {F12261
9290: 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
92a0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
92b0: 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
92c0: 6f 77 73 20 74 68 61 74 20 68 61 76 65 20 62 65  ows that have be
92d0: 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 62  en.** modified b
92e0: 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  y INSERT, UPDATE
92f0: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
9300: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
9310: 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a  database handle.
9320: 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 7b  ** was opened. {
9330: 46 31 32 32 36 32 7d 20 54 68 65 20 63 6f 75 6e  F12262} The coun
9340: 74 20 69 6e 63 6c 75 64 65 73 20 55 50 44 41 54  t includes UPDAT
9350: 45 2c 20 49 4e 53 45 52 54 20 61 6e 64 20 44 45  E, INSERT and DE
9360: 4c 45 54 45 20 0a 2a 2a 20 73 74 61 74 65 6d 65  LETE .** stateme
9370: 6e 74 73 20 65 78 65 63 75 74 65 64 20 61 73 20  nts executed as 
9380: 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
9390: 70 72 6f 67 72 61 6d 73 2e 20 20 7b 46 31 32 32  programs.  {F122
93a0: 36 33 7d 20 41 6c 6c 20 63 68 61 6e 67 65 73 0a  63} All changes.
93b0: 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  ** are counted a
93c0: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
93d0: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
93e0: 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
93f0: 65 74 65 64 20 0a 2a 2a 20 28 77 68 65 6e 20 74  eted .** (when t
9400: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
9410: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  dle is passed to
9420: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
9430: 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71 6c 69 74  )] or .** [sqlit
9440: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
9450: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65   {END}.**.** See
9460: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
9470: 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74  e3_change()] int
9480: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  erface..**.** {F
9490: 31 32 32 36 35 7d 20 53 51 4c 69 74 65 20 69 6d  12265} SQLite im
94a0: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
94b0: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
94c0: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
94d0: 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c 61 75  .** a WHERE clau
94e0: 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  se by dropping a
94f0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
9500: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
9510: 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65  is much.** faste
9520: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
9530: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
9540: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
9550: 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74 68  elements form th
9560: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
9570: 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70  se of.** this op
9580: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
9590: 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72  change count for
95a0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
95b0: 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ble" will be.** 
95c0: 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20  zero regardless 
95d0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
95e0: 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77   elements that w
95f0: 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69  ere originally i
9600: 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20  n the.** table. 
9610: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
9620: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
9630: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
9640: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
9650: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
9660: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
9670: 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36  ad..**.** {U1226
9680: 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  4} If another th
9690: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
96a0: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
96b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
96c0: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73  on.** while this
96d0: 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
96e0: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65 74  ing then the ret
96f0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
9700: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20  s routine.** is 
9710: 75 6e 64 65 66 69 6e 65 64 2e 20 7b 45 4e 44 7d  undefined. {END}
9720: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
9730: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
9740: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
9750: 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
9760: 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
9770: 6e 67 20 51 75 65 72 79 20 7b 46 31 32 32 37 30  ng Query {F12270
9780: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d  }.**.** {F12271}
9790: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63   This function c
97a0: 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
97b0: 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
97c0: 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
97d0: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
97e0: 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
97f0: 72 74 75 6e 69 74 79 2e 20 7b 45 4e 44 7d 20 54  rtunity. {END} T
9800: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
9810: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
9820: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
9830: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
9840: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
9850: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
9860: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
9870: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
9880: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
9890: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
98a0: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
98b0: 20 7b 46 31 32 32 37 32 7d 20 49 74 20 69 73 20   {F12272} It is 
98c0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
98d0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
98e0: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
98f0: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
9900: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
9910: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
9920: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
9930: 61 74 69 6f 6e 2e 20 7b 55 31 32 32 37 33 7d 20  ation. {U12273} 
9940: 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
9950: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
9960: 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
9970: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
9980: 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73  ction that.** is
9990: 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
99a0: 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
99b0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
99c0: 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
99d0: 20 49 66 20 61 6e 20 53 51 4c 20 69 73 20 76 65   If an SQL is ve
99e0: 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
99f0: 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
9a00: 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  hen sqlite3_inte
9a10: 72 72 75 70 74 28 29 0a 2a 2a 20 69 73 20 63 61  rrupt().** is ca
9a20: 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
9a30: 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
9a40: 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 62  opportunity to b
9a50: 65 20 69 6e 74 65 72 72 75 70 74 65 64 2e 0a 2a  e interrupted..*
9a60: 2a 20 49 74 20 6d 69 67 68 74 20 63 6f 6e 74 69  * It might conti
9a70: 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
9a80: 6e 2e 0a 2a 2a 20 7b 46 31 32 32 37 34 7d 20 54  n..** {F12274} T
9a90: 68 65 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  he SQL operation
9aa0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
9ab0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
9ac0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
9ad0: 52 52 55 50 54 5d 2e 20 20 7b 46 31 32 32 37 35  RRUPT].  {F12275
9ae0: 7d 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75  } If the interru
9af0: 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
9b00: 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20 49 4e 53 45  on is an.** INSE
9b10: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
9b20: 45 4c 45 54 45 20 74 68 61 74 20 69 73 20 69 6e  ELETE that is in
9b30: 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
9b40: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a   transaction, .*
9b50: 2a 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  * then the entir
9b60: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69  e transaction wi
9b70: 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
9b80: 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
9b90: 0a 2a 2a 20 7b 46 31 32 32 37 36 7d 20 41 20 63  .** {F12276} A c
9ba0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
9bb0: 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e  nterrupt() has n
9bc0: 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
9bd0: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
9be0: 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
9bf0: 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74  fter sqlite3_int
9c00: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
9c10: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
9c20: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
9c30: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
9c40: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
9c50: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
9c60: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
9c70: 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a  e {F10510}.**.**
9c80: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
9c90: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
9ca0: 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
9cb0: 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
9cc0: 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
9cd0: 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
9ce0: 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f  seems to form co
9cf0: 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61  mplete a SQL sta
9d00: 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
9d10: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
9d20: 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
9d30: 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
9d40: 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
9d50: 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
9d60: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
9d70: 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
9d80: 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
9d90: 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
9da0: 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
9db0: 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61  tatement.  A sta
9dc0: 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
9dd0: 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
9de0: 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
9df0: 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  th a semicolon a
9e00: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
9e10: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
9e20: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
9e30: 65 6d 65 6e 74 2e 20 20 54 68 65 73 65 20 72 6f  ement.  These ro
9e40: 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
9e50: 72 73 65 20 74 68 65 20 53 51 4c 20 61 6e 64 0a  rse the SQL and.
9e60: 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e 6f 74 20 64  ** so will not d
9e70: 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
9e80: 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
9e90: 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31  L..**.** {F10511
9ea0: 7d 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  } These function
9eb0: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  s return true if
9ec0: 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75 74   the given input
9ed0: 20 73 74 72 69 6e 67 20 0a 2a 2a 20 65 6e 64 73   string .** ends
9ee0: 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
9ef0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c  n optionally fol
9f00: 6c 6f 77 65 64 20 62 79 20 77 68 69 74 65 73 70  lowed by whitesp
9f10: 61 63 65 20 6f 72 0a 2a 2a 20 63 6f 6d 6d 65 6e  ace or.** commen
9f20: 74 73 2e 20 7b 46 31 30 35 31 32 7d 20 46 6f 72  ts. {F10512} For
9f30: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
9f40: 65 28 29 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61  e(),.** the para
9f50: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
9f60: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
9f70: 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 20 7b 46  UTF-8 string. {F
9f80: 31 30 35 31 33 7d 20 46 6f 72 0a 2a 2a 20 73 71  10513} For.** sq
9f90: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
9fa0: 28 29 2c 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  (), a zero-termi
9fb0: 6e 61 74 65 64 20 6d 61 63 68 69 6e 65 20 62 79  nated machine by
9fc0: 74 65 20 6f 72 64 65 72 20 55 54 46 2d 31 36 20  te order UTF-16 
9fd0: 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20 72 65 71  string.** is req
9fe0: 75 69 72 65 64 2e 20 20 7b 46 31 30 35 31 34 7d  uired.  {F10514}
9ff0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
a000: 72 65 74 75 72 6e 20 66 61 6c 73 65 20 69 66 20  return false if 
a010: 74 68 65 20 74 65 72 6d 69 6e 61 6c 0a 2a 2a 20  the terminal.** 
a020: 73 65 6d 69 63 6f 6c 6f 6e 20 69 73 20 77 69 74  semicolon is wit
a030: 68 69 6e 20 61 20 63 6f 6d 6d 65 6e 74 2c 20 61  hin a comment, a
a040: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
a050: 6f 72 20 61 20 71 75 6f 74 65 64 20 69 64 65 6e  or a quoted iden
a060: 74 69 66 69 65 72 0a 2a 2a 20 28 69 6e 20 6f 74  tifier.** (in ot
a070: 68 65 72 20 77 6f 72 64 73 20 69 66 20 74 68 65  her words if the
a080: 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
a090: 20 69 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 61   is not really a
a0a0: 20 73 65 70 61 72 61 74 65 20 74 6f 6b 65 6e 0a   separate token.
a0b0: 2a 2a 20 62 75 74 20 70 61 72 74 20 6f 66 20 61  ** but part of a
a0c0: 20 6c 61 72 67 65 72 20 74 6f 6b 65 6e 29 20 6f   larger token) o
a0d0: 72 20 69 66 20 74 68 65 20 66 69 6e 61 6c 20 73  r if the final s
a0e0: 65 6d 69 63 6f 6c 6f 6e 20 69 73 0a 2a 2a 20 69  emicolon is.** i
a0f0: 6e 20 62 65 74 77 65 65 6e 20 74 68 65 20 42 45  n between the BE
a100: 47 49 4e 20 61 6e 64 20 45 4e 44 20 6b 65 79 77  GIN and END keyw
a110: 6f 72 64 73 20 6f 66 20 61 20 43 52 45 41 54 45  ords of a CREATE
a120: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
a130: 6e 74 2e 0a 2a 2a 20 7b 45 4e 44 7d 0a 2a 2f 0a  nt..** {END}.*/.
a140: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
a150: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
a160: 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
a170: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
a180: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
a190: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a1a0: 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
a1b0: 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
a1c0: 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
a1d0: 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a  s {F12310}.**.**
a1e0: 20 7b 46 31 32 33 31 31 7d 20 54 68 69 73 20 72   {F12311} This r
a1f0: 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65  outine identifie
a200: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
a210: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
a220: 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77   be.** invoked w
a230: 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d  henever an attem
a240: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
a250: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
a260: 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f  ble .** that ano
a270: 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70  ther thread or p
a280: 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
a290: 64 2e 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 49  d..** {F12312} I
a2a0: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
a2b0: 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
a2c0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
a2d0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
a2e0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
a2f0: 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
a300: 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
a310: 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
a320: 63 6b 2e 0a 2a 2a 20 7b 46 31 32 33 31 33 7d 20  ck..** {F12313} 
a330: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
a340: 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  back is not NULL
a350: 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61  , then the.** ca
a360: 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
a370: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
a380: 61 72 67 75 6d 65 6e 74 73 2e 20 20 7b 46 31 32  arguments.  {F12
a390: 33 31 34 7d 20 54 68 65 0a 2a 2a 20 66 69 72 73  314} The.** firs
a3a0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
a3b0: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
a3c0: 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
a3d0: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
a3e0: 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
a3f0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
a400: 72 6f 75 74 69 6e 65 2e 20 20 7b 46 31 32 33 31  routine.  {F1231
a410: 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  5} The second ar
a420: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
a430: 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65 20   handler is the 
a440: 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
a450: 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
a460: 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
a470: 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
a480: 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
a490: 2e 20 20 7b 46 31 32 33 31 36 7d 20 49 66 20 74  .  {F12316} If t
a4a0: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
a4b0: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
a4c0: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
a4d0: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
a4e0: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
a4f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
a500: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
a510: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
a520: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
a530: 75 72 6e 65 64 2e 0a 2a 2a 20 7b 46 31 32 33 31  urned..** {F1231
a540: 37 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  7} If the callba
a550: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
a560: 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
a570: 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
a580: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
a590: 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
a5a0: 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
a5b0: 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
a5c0: 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
a5d0: 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
a5e0: 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
a5f0: 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20  ntee that.** it 
a600: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
a610: 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
a620: 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 7b  ck contention. {
a630: 46 31 32 33 31 39 7d 0a 2a 2a 20 49 66 20 53 51  F12319}.** If SQ
a640: 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
a650: 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
a660: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
a670: 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a  ould result in.*
a680: 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  * a deadlock, it
a690: 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
a6a0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
a6b0: 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53  E_BUSY] or.** [S
a6c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
a6d0: 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
a6e0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a 20  invoking the.** 
a6f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 7b 45  busy handler. {E
a700: 4e 44 7d 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  ND}.** Consider 
a710: 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
a720: 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
a730: 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
a740: 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
a750: 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
a760: 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
a770: 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
a780: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
a790: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
a7a0: 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
a7b0: 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
a7c0: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
a7d0: 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
a7e0: 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
a7f0: 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
a800: 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
a810: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
a820: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
a830: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
a840: 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
a850: 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
a860: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
a870: 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
a880: 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
a890: 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
a8a0: 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
a8b0: 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
a8c0: 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
a8d0: 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
a8e0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
a8f0: 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
a900: 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
a910: 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
a920: 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
a930: 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
a940: 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
a950: 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
a960: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
a970: 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
a980: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 32 31 7d 20 54  **.** {F12321} T
a990: 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
a9a0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
a9b0: 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
a9c0: 31 32 33 32 32 7d 20 54 68 65 20 5b 53 51 4c 49  12322} The [SQLI
a9d0: 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
a9e0: 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
a9f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
aa00: 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
aa10: 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
aa20: 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
aa30: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
aa40: 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
aa50: 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
aa60: 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
aa70: 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 7b 46  emory cache.  {F
aa80: 31 32 33 32 33 7d 20 53 51 4c 69 74 65 20 77 69  12323} SQLite wi
aa90: 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
aaa0: 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
aab0: 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
aac0: 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
aad0: 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
aae0: 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
aaf0: 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
ab00: 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
ab10: 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
ab20: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
ab30: 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
ab40: 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
ab50: 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 7b 46  .** readers.  {F
ab60: 31 32 33 32 34 7d 20 49 66 20 69 74 20 69 73 20  12324} If it is 
ab70: 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
ab80: 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
ab90: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
aba0: 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
abb0: 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
abc0: 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
abd0: 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
abe0: 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
abf0: 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
ac00: 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
ac10: 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
ac20: 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
ac30: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
ac40: 42 4c 4f 43 4b 45 44 5d 2e 20 20 7b 46 31 32 33  BLOCKED].  {F123
ac50: 32 35 7d 20 54 68 69 73 20 65 72 72 6f 72 20 63  25} This error c
ac60: 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
ac70: 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
ac80: 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
ac90: 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 7b 45   the changes. {E
aca0: 4e 44 7d 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  ND} See the.** <
acb0: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
acc0: 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76  ww.sqlite.org/cv
acd0: 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
ace0: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
acf0: 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
ad00: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
ad10: 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
ad20: 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
ad30: 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
ad40: 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
ad50: 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 7b  ortant..**..** {
ad60: 46 31 32 33 32 36 7d 20 53 71 6c 69 74 65 20 69  F12326} Sqlite i
ad70: 73 20 72 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f  s re-entrant, so
ad80: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
ad90: 72 20 6d 61 79 20 73 74 61 72 74 20 61 20 6e 65  r may start a ne
ada0: 77 0a 2a 2a 20 71 75 65 72 79 2e 20 7b 45 4e 44  w.** query. {END
adb0: 7d 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65  } (It is not cle
adc0: 61 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f  ar why anyone wo
add0: 75 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 74  uld every want t
ade0: 6f 20 64 6f 20 74 68 69 73 2c 0a 2a 2a 20 62 75  o do this,.** bu
adf0: 74 20 69 74 20 69 73 20 61 6c 6c 6f 77 65 64 2c  t it is allowed,
ae00: 20 69 6e 20 74 68 65 6f 72 79 2e 29 20 7b 55 31   in theory.) {U1
ae10: 32 33 32 37 7d 20 42 75 74 20 74 68 65 20 62 75  2327} But the bu
ae20: 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e  sy handler may n
ae30: 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
ae40: 64 61 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 69  database.  Closi
ae50: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
ae60: 66 72 6f 6d 20 61 20 62 75 73 79 20 68 61 6e 64  from a busy hand
ae70: 6c 65 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 20  ler will delete 
ae80: 0a 2a 2a 20 64 61 74 61 20 73 74 72 75 63 74 75  .** data structu
ae90: 72 65 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64  res out from und
aea0: 65 72 20 74 68 65 20 65 78 65 63 75 74 69 6e 67  er the executing
aeb0: 20 71 75 65 72 79 20 61 6e 64 20 77 69 6c 6c 20   query and will 
aec0: 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 73  .** probably res
aed0: 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
aee0: 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
aef0: 74 68 65 72 20 72 75 6e 74 69 6d 65 20 65 72 72  ther runtime err
af00: 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  or. {END}.**.** 
af10: 7b 46 31 32 33 32 38 7d 20 54 68 65 72 65 20 63  {F12328} There c
af20: 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
af30: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
af40: 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
af50: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
af60: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69  nnection.  Setti
af70: 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
af80: 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
af90: 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 20 0a   previous one. .
afa0: 2a 2a 20 7b 46 31 32 33 32 39 7d 20 4e 6f 74 65  ** {F12329} Note
afb0: 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
afc0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
afd0: 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f  out()] will also
afe0: 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a   set or clear.**
aff0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
b000: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 33 31  r..**.** {F12331
b010: 7d 20 57 68 65 6e 20 6f 70 65 72 61 74 69 6e 67  } When operating
b020: 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   in [sqlite3_ena
b030: 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
b040: 20 7c 20 73 68 61 72 65 64 20 63 61 63 68 65 20   | shared cache 
b050: 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61  mode],.** only a
b060: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
b070: 64 6c 65 72 20 63 61 6e 20 62 65 20 64 65 66 69  dler can be defi
b080: 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74  ned for each dat
b090: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 53  abase file..** S
b0a0: 6f 20 69 66 20 74 77 6f 20 64 61 74 61 62 61 73  o if two databas
b0b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 68  e connections sh
b0c0: 61 72 65 20 61 20 73 69 6e 67 6c 65 20 63 61 63  are a single cac
b0d0: 68 65 2c 20 74 68 65 6e 20 63 68 61 6e 67 69 6e  he, then changin
b0e0: 67 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  g.** the busy ha
b0f0: 6e 64 6c 65 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e  ndler on one con
b100: 6e 65 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 73  nection will als
b110: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 62 75 73  o change the bus
b120: 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 6e 20  y.** handler in 
b130: 74 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63  the other connec
b140: 74 69 6f 6e 2e 20 20 7b 46 31 32 33 33 32 7d 20  tion.  {F12332} 
b150: 54 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  The busy handler
b160: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 69   is invoked.** i
b170: 6e 20 74 68 65 20 74 68 72 65 61 64 20 74 68 61  n the thread tha
b180: 74 20 77 61 73 20 72 75 6e 6e 69 6e 67 20 77 68  t was running wh
b190: 65 6e 20 74 68 65 20 6c 6f 63 6b 20 63 6f 6e 74  en the lock cont
b1a0: 65 6e 74 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ention occurs..*
b1b0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
b1c0: 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
b1d0: 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
b1e0: 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
b1f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b200: 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
b210: 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a  out {F12340}.**.
b220: 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68 69 73  ** {F12341} This
b230: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
b240: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
b250: 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
b260: 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c  dler].** that sl
b270: 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65  eeps for a while
b280: 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65   when a.** table
b290: 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 7b 46 31   is locked.  {F1
b2a0: 32 33 34 32 7d 20 54 68 65 20 68 61 6e 64 6c 65  2342} The handle
b2b0: 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  r will sleep mul
b2c0: 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
b2d0: 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22  l .** at least "
b2e0: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
b2f0: 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76   of sleeping hav
b300: 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b 46 31  e been done. {F1
b310: 32 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a 20 22  2343} After.** "
b320: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
b330: 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68   of sleeping, th
b340: 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
b350: 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75  s 0 which.** cau
b360: 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
b370: 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b  p()] to return [
b380: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
b390: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
b3a0: 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  OCKED]..**.** {F
b3b0: 31 32 33 34 34 7d 20 43 61 6c 6c 69 6e 67 20 74  12344} Calling t
b3c0: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
b3d0: 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
b3e0: 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
b3f0: 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
b400: 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
b410: 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ndlers..**.** {F
b420: 31 32 33 34 35 7d 20 54 68 65 72 65 20 63 61 6e  12345} There can
b430: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
b440: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
b450: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
b460: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
b470: 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74  ection.  If anot
b480: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
b490: 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a   was defined  .*
b4a0: 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  * (using [sqlite
b4b0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
b4c0: 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
b4d0: 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
b4e0: 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
b4f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
b500: 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20  cleared..*/.int 
b510: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
b520: 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
b530: 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
b540: 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
b550: 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
b560: 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
b570: 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a  s {F12370}.**.**
b580: 20 54 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69   This next routi
b590: 6e 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ne is a convenie
b5a0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
b5b0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  nd [sqlite3_exec
b5c0: 28 29 5d 2e 0a 2a 2a 20 7b 46 31 32 33 37 31 7d  ()]..** {F12371}
b5d0: 20 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   Instead of invo
b5e0: 6b 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70 70  king a user-supp
b5f0: 6c 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f  lied callback fo
b600: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68  r each row of th
b610: 65 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68 69  e.** result, thi
b620: 73 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62  s routine rememb
b630: 65 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66 20  ers each row of 
b640: 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d 65  the result in me
b650: 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  mory.** obtained
b660: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b670: 61 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72  alloc()], then r
b680: 65 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68  eturns all of th
b690: 65 20 72 65 73 75 6c 74 20 61 66 74 65 72 20 74  e result after t
b6a0: 68 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 20  he.** query has 
b6b0: 66 69 6e 69 73 68 65 64 2e 20 7b 46 31 32 33 37  finished. {F1237
b6c0: 32 7d 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65  2}.**.** As an e
b6d0: 78 61 6d 70 6c 65 2c 20 73 75 70 70 6f 73 65 20  xample, suppose 
b6e0: 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  the query result
b6f0: 20 77 68 65 72 65 20 74 68 69 73 20 74 61 62 6c   where this tabl
b700: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  e:.**.** <blockq
b710: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
b720: 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
b730: 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
b740: 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
b750: 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
b760: 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
b770: 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
b780: 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
b790: 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
b7a0: 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
b7b0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
b7c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
b7d0: 64 20 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20  d argument were 
b7e0: 26 61 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61  &azResult then a
b7f0: 66 74 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f  fter the functio
b800: 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52  n returns.** azR
b810: 65 73 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61  esult will conta
b820: 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
b830: 20 64 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   data:.**.** <bl
b840: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
b850: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
b860: 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
b870: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
b880: 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
b890: 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
b8a0: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
b8b0: 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
b8c0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
b8d0: 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
b8e0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
b8f0: 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
b900: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
b910: 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
b920: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
b930: 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
b940: 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
b950: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
b960: 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
b970: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
b980: 2a 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61  **.** Notice tha
b990: 74 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 78  t there is an ex
b9a0: 74 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61 20  tra row of data 
b9b0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 63  containing the c
b9c0: 6f 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73  olumn.** headers
b9d0: 2e 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f 77  .  But the *nrow
b9e0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
b9f0: 20 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c   still 3.  *ncol
ba00: 75 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f  umn is.** set to
ba10: 20 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c   2.  In general,
ba20: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
ba30: 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69  alues inserted i
ba40: 6e 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20  nto azResult.** 
ba50: 77 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29  will be ((*nrow)
ba60: 20 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29   + 1)*(*ncolumn)
ba70: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 37 34 7d  ..**.** {U12374}
ba80: 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
ba90: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
baa0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
bab0: 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
bac0: 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68  ould .** pass th
bad0: 65 20 72 65 73 75 6c 74 20 64 61 74 61 20 70 6f  e result data po
bae0: 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
baf0: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
bb00: 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65   order to .** re
bb10: 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
bb20: 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
bb30: 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  -ed.  Because of
bb40: 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a   the way the .**
bb50: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
bb60: 28 29 5d 20 68 61 70 70 65 6e 73 2c 20 74 68 65  ()] happens, the
bb70: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
bb80: 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
bb90: 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69  o call .** [sqli
bba0: 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
bbb0: 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c  ctly.  Only [sql
bbc0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
bbd0: 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
bbe0: 6c 65 61 73 65 20 0a 2a 2a 20 74 68 65 20 6d 65  lease .** the me
bbf0: 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
bc00: 64 20 73 61 66 65 6c 79 2e 20 7b 45 4e 44 7d 0a  d safely. {END}.
bc10: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 54  **.** {F12373} T
bc20: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
bc30: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
bc40: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  is the same as.*
bc50: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
bc60: 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  exec()]..*/.int 
bc70: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
bc80: 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  e(.  sqlite3*,  
bc90: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
bca0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
bcb0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
bcc0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  *sql,       /* S
bcd0: 51 4c 20 74 6f 20 62 65 20 65 78 65 63 75 74 65  QL to be execute
bce0: 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 72  d */.  char ***r
bcf0: 65 73 75 6c 74 70 2c 20 20 20 20 20 20 20 2f 2a  esultp,       /*
bd00: 20 52 65 73 75 6c 74 20 77 72 69 74 74 65 6e 20   Result written 
bd10: 74 6f 20 61 20 63 68 61 72 20 2a 5b 5d 20 20 74  to a char *[]  t
bd20: 68 61 74 20 74 68 69 73 20 70 6f 69 6e 74 73 20  hat this points 
bd30: 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f  to */.  int *nro
bd40: 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  w,             /
bd50: 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
bd60: 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
bd70: 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  here */.  int *n
bd80: 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20  column,         
bd90: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
bda0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
bdb0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
bdc0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
bdd0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
bde0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
bdf0: 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
be00: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
be10: 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
be20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
be30: 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
be40: 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
be50: 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a  ns {F17400}.**.*
be60: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
be70: 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20   are workalikes 
be80: 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
be90: 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
bea0: 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
beb0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
bec0: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  rary..**.** {F17
bed0: 34 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  401} The sqlite3
bee0: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
bef0: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
bf00: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
bf10: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
bf20: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
bf30: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
bf40: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
bf50: 2a 2a 20 7b 55 31 37 34 30 32 7d 20 54 68 65 20  ** {U17402} The 
bf60: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
bf70: 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
bf80: 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
bf90: 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
bfa0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
bfb0: 2e 20 7b 46 31 37 34 30 33 7d 20 20 42 6f 74 68  . {F17403}  Both
bfc0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
bfd0: 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
bfe0: 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
bff0: 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
c000: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
c010: 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
c020: 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
c030: 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
c040: 0a 2a 2a 20 7b 46 31 37 34 30 34 7d 20 49 6e 20  .** {F17404} In 
c050: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
c060: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
c070: 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
c080: 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
c090: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
c0a0: 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
c0b0: 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
c0c0: 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
c0d0: 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
c0e0: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
c0f0: 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
c100: 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
c110: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
c120: 7b 45 4e 44 7d 20 4e 6f 74 65 20 74 68 61 74 20  {END} Note that 
c130: 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
c140: 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
c150: 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
c160: 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
c170: 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
c180: 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
c190: 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
c1a0: 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
c1b0: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
c1c0: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
c1d0: 61 74 69 62 69 6c 69 74 79 2e 20 20 7b 46 31 37  atibility.  {F17
c1e0: 34 30 35 7d 20 4e 6f 74 65 20 61 6c 73 6f 20 74  405} Note also t
c1f0: 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
c200: 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
c210: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
c220: 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
c230: 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
c240: 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
c250: 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
c260: 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
c270: 72 2e 20 7b 45 4e 44 7d 20 57 65 20 61 64 6d 69  r. {END} We admi
c280: 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
c290: 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
c2a0: 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
c2b0: 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
c2c0: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
c2d0: 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
c2e0: 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
c2f0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
c300: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
c310: 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
c320: 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
c330: 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ility..**.** {F1
c340: 37 34 30 36 7d 20 41 73 20 6c 6f 6e 67 20 61 73  7406} As long as
c350: 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
c360: 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
c370: 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
c380: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
c390: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
c3a0: 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
c3b0: 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
c3c0: 64 2e 20 7b 46 31 37 34 30 37 7d 20 54 68 65 20  d. {F17407} The 
c3d0: 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
c3e0: 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
c3f0: 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
c400: 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
c410: 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
c420: 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
c430: 6f 72 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74 68  or.  {END} So th
c440: 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
c450: 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
c460: 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
c470: 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
c480: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
c490: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
c4a0: 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
c4b0: 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
c4c0: 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
c4d0: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
c4e0: 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
c4f0: 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
c500: 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
c510: 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20  he usual printf 
c520: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
c530: 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
c540: 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
c550: 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
c560: 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
c570: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ions..**.** {F17
c580: 34 31 30 7d 20 54 68 65 20 25 71 20 6f 70 74 69  410} The %q opti
c590: 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
c5a0: 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
c5b0: 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
c5c0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
c5d0: 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
c5e0: 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
c5f0: 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
c600: 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
c610: 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
c620: 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
c630: 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
c640: 20 6c 69 74 65 72 61 6c 2e 20 7b 45 4e 44 7d 20   literal. {END} 
c650: 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
c660: 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
c670: 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
c680: 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
c690: 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
c6a0: 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
c6b0: 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
c6c0: 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
c6d0: 20 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20   so some string 
c6e0: 76 61 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e  variable contain
c6f0: 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
c700: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
c710: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
c720: 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
c730: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
c740: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
c750: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
c760: 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
c770: 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
c780: 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
c790: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
c7a0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
c7b0: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
c7c0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
c7d0: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
c7e0: 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
c7f0: 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
c800: 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
c810: 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
c820: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
c830: 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
c840: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
c850: 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
c860: 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
c870: 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
c880: 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
c890: 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
c8a0: 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
c8b0: 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
c8c0: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
c8d0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
c8e0: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
c8f0: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
c900: 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
c910: 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
c920: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
c930: 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
c940: 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
c950: 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
c960: 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
c970: 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
c980: 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
c990: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
c9a0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
c9b0: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
c9c0: 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
c9d0: 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
c9e0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
c9f0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
ca00: 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
ca10: 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
ca20: 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
ca30: 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a  eral rule you.**
ca40: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75   should always u
ca50: 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
ca60: 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
ca70: 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
ca80: 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61  tring .** litera
ca90: 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 31 31  l..**.** {F17411
caa0: 7d 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  } The %Q option 
cab0: 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
cac0: 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
cad0: 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
cae0: 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
caf0: 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
cb00: 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69  al string.  Or i
cb10: 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
cb20: 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  in the argument.
cb30: 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  ** list is a NUL
cb40: 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
cb50: 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
cb60: 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
cb70: 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f  ut single.** quo
cb80: 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66  tes) in place of
cb90: 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20   the %Q option. 
cba0: 7b 45 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65  {END}  So, for e
cbb0: 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
cbc0: 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
cbd0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
cbe0: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
cbf0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
cc00: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
cc10: 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
cc20: 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
cc30: 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
cc40: 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
cc50: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
cc60: 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
cc70: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
cc80: 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
cc90: 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
cca0: 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
ccb0: 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
ccc0: 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
ccd0: 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
cce0: 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
ccf0: 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
cd00: 20 7b 46 31 37 34 31 32 7d 20 54 68 65 20 22 25   {F17412} The "%
cd10: 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
cd20: 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74  tion works exact
cd30: 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74  ly like "%s" wit
cd40: 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
cd50: 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
cd60: 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
cd70: 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
cd80: 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
cd90: 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
cda0: 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
cdb0: 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
cdc0: 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 63 68  ing. {END}.*/.ch
cdd0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
cde0: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
cdf0: 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
ce00: 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
ce10: 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
ce20: 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
ce30: 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
ce40: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
ce50: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
ce60: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
ce70: 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
ce80: 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a  stem {F17300}.**
ce90: 0a 2a 2a 20 7b 46 31 37 33 30 31 7d 20 54 68 65  .** {F17301} The
cea0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73   SQLite core  us
ceb0: 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
cec0: 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
ced0: 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
cee0: 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
cef0: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
cf00: 7b 45 4e 44 7d 20 20 22 43 6f 72 65 22 20 69 6e  {END}  "Core" in
cf10: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
cf20: 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
cf30: 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
cf40: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
cf50: 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
cf60: 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
cf70: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   windows VFS use
cf80: 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 20  s native malloc 
cf90: 61 6e 64 20 66 72 65 65 20 66 6f 72 20 73 6f 6d  and free for som
cfa0: 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
cfb0: 0a 2a 2a 20 7b 46 31 37 33 30 32 7d 20 54 68 65  .** {F17302} The
cfc0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
cfd0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
cfe0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
cff0: 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
d000: 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
d010: 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
d020: 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
d030: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 7b 46 31  arameter..** {F1
d040: 37 33 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  7303} If sqlite3
d050: 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
d060: 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
d070: 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
d080: 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
d090: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
d0a0: 65 72 2e 20 20 7b 46 31 37 33 30 34 7d 20 49 66  er.  {F17304} If
d0b0: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
d0c0: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
d0d0: 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
d0e0: 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
d0f0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
d100: 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
d110: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
d120: 2a 2a 20 7b 46 31 37 33 30 35 7d 20 43 61 6c 6c  ** {F17305} Call
d130: 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
d140: 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
d150: 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
d160: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
d170: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
d180: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
d190: 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
d1a0: 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
d1b0: 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
d1c0: 75 73 65 64 2e 20 20 7b 46 31 37 33 30 36 7d 20  used.  {F17306} 
d1d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
d1e0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
d1f0: 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
d200: 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
d210: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
d220: 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
d230: 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
d240: 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
d250: 65 73 73 2e 20 20 7b 55 31 37 33 30 37 7d 20 41  ess.  {U17307} A
d260: 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
d270: 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
d280: 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
d290: 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
d2a0: 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
d2b0: 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
d2c0: 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
d2d0: 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
d2e0: 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
d2f0: 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
d300: 72 6f 72 2e 0a 2a 2a 20 7b 55 31 37 33 30 39 7d  ror..** {U17309}
d310: 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
d320: 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
d330: 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
d340: 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
d350: 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
d360: 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
d370: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
d380: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
d390: 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
d3a0: 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
d3b0: 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
d3c0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72  () or sqlite3_fr
d3d0: 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ee()..**.** {F17
d3e0: 33 31 30 7d 20 54 68 65 20 73 71 6c 69 74 65 33  310} The sqlite3
d3f0: 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
d400: 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
d410: 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
d420: 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
d430: 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
d440: 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
d450: 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
d460: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
d470: 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
d480: 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
d490: 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
d4a0: 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
d4b0: 20 20 7b 46 31 37 33 31 31 7d 20 49 66 20 74 68    {F17311} If th
d4c0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
d4d0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
d4e0: 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
d4f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
d500: 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
d510: 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
d520: 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
d530: 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
d540: 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
d550: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
d560: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
d570: 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 49 66 20  .** {F17312} If 
d580: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
d590: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
d5a0: 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
d5b0: 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
d5c0: 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
d5d0: 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
d5e0: 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
d5f0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
d600: 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
d610: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
d620: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
d630: 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 7b 46 31  ealloc()..** {F1
d640: 37 33 31 33 7d 20 53 71 6c 69 74 65 33 5f 72 65  7313} Sqlite3_re
d650: 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
d660: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
d670: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d680: 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
d690: 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
d6a0: 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
d6b0: 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
d6c0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
d6d0: 7b 46 31 37 33 31 34 7d 20 49 66 20 4d 20 69 73  {F17314} If M is
d6e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
d6f0: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
d700: 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
d710: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
d720: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
d730: 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
d740: 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
d750: 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
d760: 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
d770: 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
d780: 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
d790: 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
d7a0: 20 7b 46 31 37 33 31 35 7d 20 49 66 20 73 71 6c   {F17315} If sql
d7b0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
d7c0: 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
d7d0: 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
d7e0: 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
d7f0: 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46   freed..**.** {F
d800: 31 37 33 31 36 7d 20 54 68 65 20 6d 65 6d 6f 72  17316} The memor
d810: 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
d820: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
d830: 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
d840: 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
d850: 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
d860: 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
d870: 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a  boundary. {END}.
d880: 2a 2a 0a 2a 2a 20 7b 46 31 37 33 38 31 7d 20 54  **.** {F17381} T
d890: 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
d8a0: 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
d8b0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d8c0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
d8d0: 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28  uses the malloc(
d8e0: 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  ), realloc().** 
d8f0: 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69  and free() provi
d900: 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64  ded by the stand
d910: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b  ard C library. {
d920: 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  F17382} However,
d930: 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69   if .** SQLite i
d940: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
d950: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20  the following C 
d960: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
d970: 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  ro.**.** <blockq
d980: 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d  uote> SQLITE_MEM
d990: 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c  ORY_SIZE=<i>NNN<
d9a0: 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  /i> </blockquote
d9b0: 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69  >.**.** where <i
d9c0: 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69  >NNN</i> is an i
d9d0: 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c  nteger, then SQL
d9e0: 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
d9f0: 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20  tic.** array of 
da00: 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c  at least <i>NNN<
da10: 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
da20: 65 20 61 6e 64 20 75 73 65 20 74 68 61 74 20 61  e and use that a
da30: 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20  rray.** for all 
da40: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
da50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
da60: 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41   needs. {END}  A
da70: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d  dditional.** mem
da80: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
da90: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
daa0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
dab0: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  eases..**.** In 
dac0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
dad0: 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
dae0: 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
daf0: 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
db00: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
db10: 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
db20: 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
db30: 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
db40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
db50: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
db60: 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
db70: 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
db80: 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
db90: 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
dba0: 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
dbb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
dbc0: 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a   be.** used..**.
dbd0: 2a 2a 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f  ** The windows O
dbe0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
dbf0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
dc00: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
dc10: 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
dc20: 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
dc30: 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
dc40: 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
dc50: 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
dc60: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
dc70: 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
dc80: 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
dc90: 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
dca0: 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a  cular windows.**
dcb0: 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
dcc0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
dcd0: 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
dce0: 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
dcf0: 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
dd00: 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
dd10: 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
dd20: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
dd30: 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
dd40: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 76 6f  TE_NOMEM]..*/.vo
dd50: 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
dd60: 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
dd70: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
dd80: 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
dd90: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
dda0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
ddb0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
ddc0: 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
ddd0: 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a  cs {F17370}.**.*
dde0: 2a 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * In addition to
ddf0: 20 74 68 65 20 62 61 73 69 63 20 74 68 72 65 65   the basic three
de00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
de10: 69 6e 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ines .** [sqlite
de20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
de30: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
de40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
de50: 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 74 68 65 20 6d  loc()],.** the m
de60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
de70: 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c 75   subsystem inclu
de80: 64 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ded with the SQL
de90: 69 74 65 0a 2a 2a 20 73 6f 75 72 63 65 73 20 70  ite.** sources p
dea0: 72 6f 76 69 64 65 73 20 74 68 65 20 69 6e 74 65  rovides the inte
deb0: 72 66 61 63 65 73 20 73 68 6f 77 6e 20 68 65 72  rfaces shown her
dec0: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31  e..**.** {F17371
ded0: 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 65  } The sqlite3_me
dee0: 6d 6f 72 79 5f 75 73 65 64 28 29 20 72 6f 75 74  mory_used() rout
def0: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
df00: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
df10: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  es of memory cur
df20: 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
df30: 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
df40: 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
df50: 7b 46 31 37 33 37 32 7d 20 54 68 65 20 76 61 6c  {F17372} The val
df60: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
df70: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
df80: 65 64 28 29 20 69 6e 63 6c 75 64 65 73 0a 2a 2a  ed() includes.**
df90: 20 61 6e 79 20 6f 76 65 72 68 65 61 64 20 61 64   any overhead ad
dfa0: 64 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 62  ded by SQLite, b
dfb0: 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
dfc0: 61 64 64 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  added by the.** 
dfd0: 6c 69 62 72 61 72 79 20 6d 61 6c 6c 6f 63 28 29  library malloc()
dfe0: 20 74 68 61 74 20 62 61 63 6b 73 20 74 68 65 20   that backs the 
dff0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
e000: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
e010: 0a 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54 68 65  .** {F17373} The
e020: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
e030: 68 69 67 68 77 61 74 65 72 28 29 20 72 6f 75 74  highwater() rout
e040: 69 6e 65 73 20 72 65 74 75 72 6e 73 20 74 68 65  ines returns the
e050: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
e060: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
e070: 20 68 61 76 65 20 62 65 65 6e 20 6f 75 74 73 74   have been outst
e080: 61 6e 64 69 6e 67 20 61 74 20 61 6e 79 20 74 69  anding at any ti
e090: 6d 65 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  me.** since the 
e0a0: 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 77  highwater mark w
e0b0: 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a  as last reset..*
e0c0: 2a 20 7b 46 31 37 33 37 34 7d 20 54 68 65 20 62  * {F17374} The b
e0d0: 79 74 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  yte count return
e0e0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 65  ed by sqlite3_me
e0f0: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
e100: 0a 2a 2a 20 75 73 65 73 20 74 68 65 20 73 61 6d  .** uses the sam
e110: 65 20 62 79 74 65 20 63 6f 75 6e 74 69 6e 67 20  e byte counting 
e120: 72 75 6c 65 73 20 61 73 20 73 71 6c 69 74 65 33  rules as sqlite3
e130: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 2e 20  _memory_used(). 
e140: 7b 45 4e 44 7d 0a 2a 2a 20 49 6e 20 6f 74 68 65  {END}.** In othe
e150: 72 20 77 6f 72 64 73 2c 20 6f 76 65 72 68 65 61  r words, overhea
e160: 64 20 61 64 64 65 64 20 69 6e 74 65 72 6e 61 6c  d added internal
e170: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 69 73 20  ly by SQLite is 
e180: 63 6f 75 6e 74 65 64 2c 0a 2a 2a 20 62 75 74 20  counted,.** but 
e190: 6f 76 65 72 68 65 61 64 20 66 72 6f 6d 20 74 68  overhead from th
e1a0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  e underlying sys
e1b0: 74 65 6d 20 6d 61 6c 6c 6f 63 20 69 73 20 6e 6f  tem malloc is no
e1c0: 74 2e 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20 49  t..** {F17375} I
e1d0: 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
e1e0: 74 6f 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  to sqlite3_memor
e1f0: 79 5f 68 69 67 68 77 61 74 65 72 28 29 20 69 73  y_highwater() is
e200: 20 74 72 75 65 2c 0a 2a 2a 20 74 68 65 6e 20 74   true,.** then t
e210: 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  he highwater mar
e220: 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
e230: 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
e240: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 65  of.** sqlite3_me
e250: 6d 6f 72 79 5f 75 73 65 64 28 29 20 61 6e 64 20  mory_used() and 
e260: 74 68 65 20 70 72 69 6f 72 20 68 69 67 68 77 61  the prior highwa
e270: 74 65 72 20 6d 61 72 6b 20 28 62 65 66 6f 72 65  ter mark (before
e280: 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 29 20 69   the.** reset) i
e290: 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46 31  s returned.  {F1
e2a0: 37 33 37 36 7d 20 20 49 66 20 74 68 65 20 70 61  7376}  If the pa
e2b0: 72 61 6d 65 74 65 72 20 74 6f 20 0a 2a 2a 20 73  rameter to .** s
e2c0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
e2d0: 67 68 77 61 74 65 72 28 29 20 69 73 20 7a 65 72  ghwater() is zer
e2e0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 68  o, then the high
e2f0: 77 61 74 65 72 20 6d 61 72 6b 20 69 73 0a 2a 2a  water mark is.**
e300: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 73   unchanged..*/.s
e310: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
e320: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
e330: 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
e340: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
e350: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
e360: 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
e370: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e380: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
e390: 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
e3a0: 61 63 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a  acks {F12500}.**
e3b0: 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68 69  .** {F12501} Thi
e3c0: 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
e3d0: 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
e3e0: 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
e3f0: 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 64   particular.** d
e400: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e410: 6f 6e 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  on, supplied in 
e420: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e430: 6e 74 2e 20 7b 46 31 32 35 30 32 7d 0a 2a 2a 20  nt. {F12502}.** 
e440: 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
e450: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
e460: 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
e470: 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
e480: 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
e490: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
e4a0: 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
e4b0: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
e4c0: 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
e4d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
e4e0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
e4f0: 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
e500: 20 20 7b 46 31 32 35 30 33 7d 20 41 74 20 76 61    {F12503} At va
e510: 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
e520: 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
e530: 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
e540: 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
e550: 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
e560: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
e570: 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
e580: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
e590: 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
e5a0: 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
e5b0: 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
e5c0: 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
e5d0: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
e5e0: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51  uld.** return SQ
e5f0: 4c 49 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77  LITE_OK to allow
e600: 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
e610: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
e620: 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
e630: 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
e640: 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
e650: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
e660: 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
e670: 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
e680: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
e690: 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
e6a0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
e6b0: 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
e6c0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
e6d0: 7b 46 31 32 35 30 34 7d 20 49 66 20 74 68 65 20  {F12504} If the 
e6e0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
e6f0: 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
e700: 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
e710: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
e720: 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
e730: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
e740: 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  Y].** then [sqli
e750: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
e760: 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
e770: 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
e780: 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
e790: 72 69 7a 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 66  rizer shall.** f
e7a0: 61 69 6c 20 77 69 74 68 20 61 6e 20 53 51 4c 49  ail with an SQLI
e7b0: 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 20 63  TE_ERROR error c
e7c0: 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  ode and an appro
e7d0: 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
e7e0: 73 61 67 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  sage. {END}.**.*
e7f0: 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
e800: 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
e810: 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
e820: 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
e830: 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
e840: 73 20 6f 6b 2e 20 20 7b 46 31 32 35 30 35 7d 20  s ok.  {F12505} 
e850: 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
e860: 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
e870: 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
e880: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
e890: 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
e8a0: 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
e8b0: 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
e8c0: 61 75 74 68 6f 72 69 7a 65 72 20 73 68 61 6c 6c  authorizer shall
e8d0: 20 66 61 69 6c 0a 2a 2a 20 77 69 74 68 20 61 6e   fail.** with an
e8e0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
e8f0: 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
e900: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
e910: 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
e920: 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
e930: 64 2e 20 7b 46 31 32 35 30 36 7d 20 49 66 20 74  d. {F12506} If t
e940: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
e950: 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
e960: 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
e970: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
e980: 61 63 6b 20 69 73 20 61 6e 79 74 68 69 6e 67 20  ack is anything 
e990: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
e9a0: 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a  TE_READ], then.*
e9b0: 2a 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53  * a return of [S
e9c0: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61  QLITE_IGNORE] ha
e9d0: 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
e9e0: 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  t as [SQLITE_DEN
e9f0: 59 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20 61  Y]. .** If the a
ea00: 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69  uthorizer code i
ea10: 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  s [SQLITE_READ] 
ea20: 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
ea30: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
ea40: 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
ea50: 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
ea60: 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
ea70: 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 69 6e 73  ructed to.** ins
ea80: 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  ert a NULL value
ea90: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
eaa0: 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
eab0: 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
eac0: 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
ead0: 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
eae0: 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 7b 45 4e  en returned. {EN
eaf0: 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30  D}.**.** {F12510
eb00: 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
eb10: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
eb20: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
eb30: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
eb40: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
eb50: 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
eb60: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
eb70: 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
eb80: 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20  ** {F12511} The 
eb90: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
eba0: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
ebb0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a   is an integer .
ebc0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  ** [SQLITE_COPY 
ebd0: 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
ebe0: 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
ebf0: 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
ec00: 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74  ion.** to be aut
ec10: 68 6f 72 69 7a 65 64 2e 20 7b 45 4e 44 7d 20 54  horized. {END} T
ec20: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 61 63 74  he available act
ec30: 69 6f 6e 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ion codes are.**
ec40: 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
ec50: 64 6f 63 75 6d 65 6e 74 65 64 20 73 65 70 61 72  documented separ
ec60: 61 74 65 6c 79 5d 2e 20 20 7b 46 31 32 35 31 32  ately].  {F12512
ec70: 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  } The third thro
ec80: 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72  ugh sixth.** par
ec90: 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
eca0: 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
ecb0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
ecc0: 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
ecd0: 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20   .** additional 
ece0: 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
ecf0: 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
ed00: 75 74 68 6f 72 69 7a 65 64 2e 20 7b 45 4e 44 7d  uthorized. {END}
ed10: 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
ed20: 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
ed30: 6e 20 70 72 65 70 61 72 69 6e 67 20 53 51 4c 20  n preparing SQL 
ed40: 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
ed50: 61 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20  an untrusted.** 
ed60: 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
ed70: 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
ed80: 74 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74  tatements do not
ed90: 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
eda0: 61 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79  ata.** that they
edb0: 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
edc0: 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
edd0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79   they do not try
ede0: 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d   to.** execute m
edf0: 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
ee00: 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
ee10: 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
ee20: 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
ee30: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
ee40: 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
ee50: 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
ee60: 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
ee70: 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
ee80: 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
ee90: 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
eea0: 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
eeb0: 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
eec0: 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
eed0: 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
eee0: 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
eef0: 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
ef00: 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
ef10: 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
ef20: 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
ef30: 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
ef40: 73 20 62 65 69 6e 67 20 70 72 65 70 61 72 65 64  s being prepared
ef50: 20 74 68 61 74 20 64 69 73 61 6c 6c 6f 77 73 20   that disallows 
ef60: 65 76 65 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78  everything.** ex
ef70: 63 65 70 74 20 53 45 4c 45 43 54 20 73 74 61 74  cept SELECT stat
ef80: 65 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20  ements.  .**.** 
ef90: 7b 46 31 32 35 32 30 7d 20 4f 6e 6c 79 20 61 20  {F12520} Only a 
efa0: 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
efb0: 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
efc0: 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
efd0: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
efe0: 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
eff0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f000: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
f010: 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
f020: 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 7b 46  revious call. {F
f030: 31 32 35 32 31 7d 20 20 41 20 4e 55 4c 4c 20 61  12521}  A NULL a
f040: 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
f050: 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
f060: 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
f070: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 7b  k is invoked.  {
f080: 46 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61  F12522} The defa
f090: 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69  ult authorizer i
f0a0: 73 20 4e 55 4c 4c 2e 20 7b 45 4e 44 7d 0a 2a 2a  s NULL. {END}.**
f0b0: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
f0c0: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
f0d0: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
f0e0: 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a   only during .**
f0f0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
f100: 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
f110: 61 6e 74 73 2e 20 20 7b 46 31 32 35 32 33 7d 20  ants.  {F12523} 
f120: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
f130: 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
f140: 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
f150: 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
f160: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
f170: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20  ]. {END}.*/.int 
f180: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
f190: 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
f1a0: 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
f1b0: 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
f1c0: 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
f1d0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
f1e0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
f1f0: 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
f200: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
f210: 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
f220: 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 46 31  Return Codes {F1
f230: 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2590}.**.** The 
f240: 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
f250: 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
f260: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
f270: 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
f280: 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
f290: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
f2a0: 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
f2b0: 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
f2c0: 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
f2d0: 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
f2e0: 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
f2f0: 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
f300: 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
f310: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
f320: 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
f330: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
f340: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
f350: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
f360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
f370: 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
f380: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
f390: 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
f3a0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
f3b0: 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
f3c0: 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
f3d0: 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
f3e0: 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
f3f0: 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
f400: 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
f410: 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46   Action Codes {F
f420: 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12550}.**.** The
f430: 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
f440: 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
f450: 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
f460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
f470: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
f480: 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
f490: 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51 4c  izer certain SQL
f4a0: 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
f4b0: 6e 73 2e 20 20 7b 46 31 32 35 35 31 7d 20 54 68  ns.  {F12551} Th
f4c0: 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
f4d0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
f4e0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
f4f0: 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
f500: 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
f510: 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
f520: 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
f530: 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
f540: 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
f550: 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
f560: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
f570: 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 20 7b  may be passed. {
f580: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
f590: 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
f5a0: 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
f5b0: 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
f5c0: 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20  on is to be .** 
f5d0: 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 7b 46 31  authorized.  {F1
f5e0: 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e  2552} The 3rd an
f5f0: 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
f600: 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
f610: 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
f620: 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
f630: 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
f640: 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
f650: 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
f660: 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
f670: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
f680: 20 70 61 72 61 6d 65 74 65 72 2e 20 7b 46 31 32   parameter. {F12
f690: 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
f6a0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
f6b0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
f6c0: 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
f6d0: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
f6e0: 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
f6f0: 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  , .** etc.) if a
f700: 70 70 6c 69 63 61 62 6c 65 2e 20 7b 46 31 32 35  pplicable. {F125
f710: 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61  54} The 6th para
f720: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
f730: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
f740: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
f750: 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
f760: 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
f770: 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
f780: 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
f790: 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
f7a0: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
f7b0: 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
f7c0: 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20  s directly from 
f7d0: 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
f7e0: 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
f7f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
f800: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
f810: 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
f820: 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
f830: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
f840: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
f850: 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
f860: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
f870: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
f880: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
f890: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
f8a0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
f8b0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
f8c0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
f8d0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
f8e0: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
f8f0: 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
f900: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
f910: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
f920: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
f930: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
f940: 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
f950: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
f960: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
f970: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
f980: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
f990: 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
f9a0: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
f9b0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
f9c0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
f9d0: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
f9e0: 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
f9f0: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
fa00: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
fa10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
fa20: 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
fa30: 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
fa40: 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
fa50: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
fa60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fa70: 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
fa80: 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
fa90: 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
faa0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
fab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fac0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
fad0: 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
fae0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
faf0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
fb00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fb10: 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
fb20: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
fb30: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
fb40: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
fb50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
fb60: 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
fb70: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
fb80: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
fb90: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
fba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
fbb0: 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
fbc0: 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
fbd0: 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
fbe0: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
fbf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
fc00: 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
fc10: 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
fc20: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
fc30: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
fc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
fc50: 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
fc60: 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
fc70: 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
fc80: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
fc90: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
fca0: 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
fcb0: 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
fcc0: 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
fcd0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
fce0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
fcf0: 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
fd00: 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
fd10: 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
fd20: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
fd30: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
fd40: 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
fd50: 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
fd60: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
fd70: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
fd80: 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
fd90: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
fda0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
fdb0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
fdc0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
fdd0: 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
fde0: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
fdf0: 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
fe00: 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
fe10: 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
fe20: 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
fe30: 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
fe40: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
fe50: 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
fe60: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
fe70: 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
fe80: 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
fe90: 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
fea0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
feb0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
fec0: 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
fed0: 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
fee0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
fef0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
ff00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ff10: 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
ff20: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
ff30: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
ff40: 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
ff50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ff60: 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
ff70: 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
ff80: 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
ff90: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
ffa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ffb0: 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
ffc0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
ffd0: 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
ffe0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
fff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10000 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
10010 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
10020 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
10030 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
10040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
10050 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
10060 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
10070 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
10080 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
10090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
100a0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
100b0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
100c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
100d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
100e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
100f0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
10100 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
10110 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
10120 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
10130 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
10140 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
10150 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
10160 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
10170 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
10180 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
10190 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
101a0 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e  31   /* Function
101b0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
101c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
101d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
101e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
101f0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
10200 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
10210 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
10220 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
10230 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38  Functions {F1228
10240 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
10250 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
10260 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
10270 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
10280 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
10290 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
102a0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
102b0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
102c0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31  s..**.** {F12281
102d0 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
102e0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
102f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
10300 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
10310 0a 2a 2a 20 61 74 20 74 68 65 20 66 69 72 73 74  .** at the first
10320 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10330 5d 20 66 6f 72 20 74 68 65 20 65 76 61 6c 75 61  ] for the evalua
10340 74 69 6f 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73  tion of an SQL s
10350 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 7b 46 31  tatement..** {F1
10360 32 32 38 32 7d 20 4f 6e 6c 79 20 61 20 73 69 6e  2282} Only a sin
10370 67 6c 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  gle trace callba
10380 63 6b 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ck can be regist
10390 65 72 65 64 20 61 74 20 61 20 74 69 6d 65 2e 0a  ered at a time..
103a0 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  ** Each call to 
103b0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
103c0 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 70 72  overrides the pr
103d0 65 76 69 6f 75 73 2e 20 20 7b 46 31 32 32 38 33  evious.  {F12283
103e0 7d 20 41 0a 2a 2a 20 4e 55 4c 4c 20 63 61 6c 6c  } A.** NULL call
103f0 62 61 63 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  back for sqlite3
10400 5f 74 72 61 63 65 28 29 20 64 69 73 61 62 6c 65  _trace() disable
10410 73 20 74 72 61 63 69 6e 67 2e 20 20 7b 46 31 32  s tracing.  {F12
10420 32 38 34 7d 20 54 68 65 0a 2a 2a 20 66 69 72 73  284} The.** firs
10430 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10440 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
10450 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
10460 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  e pointer which.
10470 2a 2a 20 77 61 73 20 74 68 65 20 33 72 64 20 61  ** was the 3rd a
10480 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10490 65 33 5f 74 72 61 63 65 2e 20 20 7b 46 31 32 32  e3_trace.  {F122
104a0 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61  85} The second a
104b0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
104c0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
104d0 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
104e0 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e  nated UTF8 strin
104f0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  g containing.** 
10500 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78  the original tex
10510 74 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  t of the SQL sta
10520 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
10530 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
10540 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
10550 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 65 71  _v2()] or the eq
10560 75 69 76 61 6c 65 6e 74 2e 20 7b 45 4e 44 7d 20  uivalent. {END} 
10570 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 0a 2a   Note that the.*
10580 2a 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  * host parameter
10590 20 61 72 65 20 6e 6f 74 20 65 78 70 61 6e 64 65   are not expande
105a0 64 20 69 6e 20 74 68 65 20 53 51 4c 20 73 74 61  d in the SQL sta
105b0 74 65 6d 65 6e 74 20 74 65 78 74 2e 0a 2a 2a 0a  tement text..**.
105c0 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20  ** {F12287} The 
105d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
105e0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
105f0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
10600 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
10610 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
10620 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
10630 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20 66 69   {F12288} The fi
10640 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
10650 20 74 68 65 0a 2a 2a 20 70 72 6f 66 69 6c 65 20   the.** profile 
10660 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
10670 70 79 20 6f 66 20 74 68 65 20 33 72 64 20 70 61  py of the 3rd pa
10680 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
10690 65 33 5f 70 72 6f 66 69 6c 65 28 29 2e 0a 2a 2a  e3_profile()..**
106a0 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20 73 65   {F12289} The se
106b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
106c0 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
106d0 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 7a  llback is a.** z
106e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
106f0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74  TF-8 string that
10700 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f   contains the co
10710 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a  mplete text of.*
10720 2a 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  * the SQL statem
10730 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72  ent as it was pr
10740 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69  ocessed by [sqli
10750 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
10760 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69  ] or.** the equi
10770 76 61 6c 65 6e 74 2e 20 20 7b 46 31 32 32 39 30  valent.  {F12290
10780 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61  } The third para
10790 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
107a0 66 69 6c 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63  file .** callbac
107b0 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  k is an estimate
107c0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
107d0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66  f nanoseconds of
107e0 0a 2a 2a 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74  .** wall-clock t
107f0 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f 20  ime required to 
10800 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
10810 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
10820 0a 2a 2a 20 74 6f 20 66 69 6e 69 73 68 2e 20 7b  .** to finish. {
10830 45 4e 44 7d 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  END}  .**.** The
10840 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
10850 28 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e  () API is curren
10860 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65  tly considered e
10870 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a  xperimental and.
10880 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  ** is subject to
10890 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64   change..*/.void
108a0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
108b0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
108c0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
108d0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
108e0 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
108f0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
10900 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
10910 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
10920 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
10930 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
10940 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10950 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
10960 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  s Callbacks {F12
10970 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  910}.**.** {F129
10980 31 31 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  11} This routine
10990 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
109a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
109b0 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73  - the.** progres
109c0 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
109d0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  t is invoked per
109e0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
109f0 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67   long.** running
10a00 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
10a10 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
10a20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
10a30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
10a40 5f 74 61 62 6c 65 28 29 5d 2e 20 7b 45 4e 44 7d  _table()]. {END}
10a50 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
10a60 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e   for this .** in
10a70 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
10a80 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
10a90 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
10aa0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  query..**.** {F1
10ab0 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
10ac0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
10ad0 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
10ae0 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
10af0 2a 2a 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64  ** machine opcod
10b00 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
10b10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10b20 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
10b30 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 32 39 31 33 7d  ion..** {F12913}
10b40 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
10b50 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73  llback itself is
10b60 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
10b70 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
10b80 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
10b90 63 74 69 6f 6e 2e 20 7b 46 31 32 39 31 34 7d 20  ction. {F12914} 
10ba0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
10bb0 65 6e 74 20 74 6f 20 74 68 69 73 0a 2a 2a 20 66  ent to this.** f
10bc0 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f 69  unction is a voi
10bd0 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
10be0 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
10bf0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
10c00 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20  ction each time 
10c10 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 7b  it is invoked. {
10c20 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  END}.**.** {F129
10c30 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  15} If a call to
10c40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
10c50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
10c60 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
10c70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
10c80 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65   results in fewe
10c90 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73  r than N opcodes
10ca0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
10cb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 72 6f  .** then the pro
10cc0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
10cd0 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e  s never invoked.
10ce0 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46   {END}.** .** {F
10cf0 31 32 39 31 36 7d 20 4f 6e 6c 79 20 61 20 73 69  12916} Only a si
10d00 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 63 61  ngle progress ca
10d10 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
10d20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
10d30 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 6f 70  d for each.** op
10d40 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
10d50 65 63 74 69 6f 6e 2e 20 20 45 76 65 72 79 20 63  ection.  Every c
10d60 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  all to sqlite3_p
10d70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
10d80 29 0a 2a 2a 20 6f 76 65 72 77 72 69 74 65 73 20  ).** overwrites 
10d90 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 74  the results of t
10da0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
10db0 2e 20 7b 46 31 32 39 31 37 7d 0a 2a 2a 20 54 6f  . {F12917}.** To
10dc0 20 72 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67   remove the prog
10dd0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c  ress callback al
10de0 74 6f 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e  together, pass N
10df0 55 4c 4c 20 61 73 20 74 68 65 20 74 68 69 72 64  ULL as the third
10e00 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
10e10 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  this function. {
10e20 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  END}.**.** {F129
10e30 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  18} If the progr
10e40 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
10e50 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74  urns a result ot
10e60 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e  her than 0, then
10e70 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
10e80 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61  query is immedia
10e90 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20  tely terminated 
10ea0 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 65  and any database
10eb0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 72 6f 6c 6c   changes.** roll
10ec0 65 64 20 62 61 63 6b 2e 20 7b 46 31 32 39 31 39  ed back. {F12919
10ed0 7d 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69 6e  }.** The contain
10ee0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
10ef0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
10f00 74 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  tep()], or.** [s
10f10 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
10f20 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
10f30 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
10f40 54 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 20 66  T. {END}  This f
10f50 65 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65  eature.** can be
10f60 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
10f70 6c 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  le, to implement
10f80 20 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75   the "Cancel" bu
10f90 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f  tton on a.** pro
10fa0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
10fb0 20 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f   in a GUI..*/.vo
10fc0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
10fd0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
10fe0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
10ff0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
11000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11010 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
11020 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
11030 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a  tion {F12700}.**
11040 0a 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65  .** {F12701} The
11050 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
11060 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
11070 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
11080 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20  ame.** is given 
11090 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  by the filename 
110a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 7b 46 31  argument..** {F1
110b0 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61  2702} The filena
110c0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
110d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
110e0 46 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c 69  F-8.** for [sqli
110f0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
11100 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
11110 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31  ()] and as UTF-1
11120 36 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  6.** in the nati
11130 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
11140 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
11150 36 28 29 5d 2e 0a 2a 2a 20 7b 46 31 32 37 30 33  6()]..** {F12703
11160 7d 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20  } An [sqlite3*] 
11170 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75 72 6e  handle is return
11180 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
11190 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72  n.** if an error
111a0 20 6f 63 63 75 72 73 2e 20 20 7b 46 31 32 37 32   occurs.  {F1272
111b0 33 7d 20 28 45 78 63 65 70 74 69 6f 6e 3a 20 69  3} (Exception: i
111c0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
111d0 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61 74  le.** to allocat
111e0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
111f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
11200 62 6a 65 63 74 2c 20 61 20 4e 55 4c 4c 20 77 69  bject, a NULL wi
11210 6c 6c 0a 2a 2a 20 62 65 20 77 72 69 74 74 65 6e  ll.** be written
11220 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
11230 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
11240 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11250 5d 20 6f 62 6a 65 63 74 2e 29 0a 2a 2a 20 7b 46  ] object.).** {F
11260 31 32 37 30 34 7d 20 49 66 20 74 68 65 20 64 61  12704} If the da
11270 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
11280 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
11290 29 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  ).** successfull
112a0 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  y, then [SQLITE_
112b0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
112c0 20 20 7b 46 31 32 37 30 35 7d 20 4f 74 68 65 72    {F12705} Other
112d0 77 69 73 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  wise an.** error
112e0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
112f0 64 2e 20 20 7b 46 31 32 37 30 36 7d 20 54 68 65  d.  {F12706} The
11300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
11310 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
11320 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20  e3_errmsg16()]  
11330 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
11340 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
11350 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
11360 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
11370 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a  n of the error..
11380 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37 7d 20 54  **.** {F12707} T
11390 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
113a0 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
113b0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
113c0 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  -8 if.** [sqlite
113d0 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
113e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
113f0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
11400 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
11410 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
11420 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
11430 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2e  en16()] is used.
11440 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 38 7d 20  .**.** {F12708} 
11450 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
11460 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
11470 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
11480 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
11490 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
114a0 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  he [sqlite3*] ha
114b0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
114c0 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69  eleased by passi
114d0 6e 67 20 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ng it.** to [sql
114e0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
114f0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
11500 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
11510 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65 20  ** {F12709} The 
11520 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
11530 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
11540 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  rks like [sqlite
11550 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20 65 78  3_open()] .** ex
11560 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
11570 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
11580 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
11590 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
115a0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
115b0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
115c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 7b 46 31  connection.  {F1
115d0 32 37 31 30 7d 20 54 68 65 20 66 6c 61 67 73 20  2710} The flags 
115e0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
115f0 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a  .** one of:.**.*
11600 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ol>.** <li>  
11610 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
11620 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  DONLY].** <li>  
11630 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
11640 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  DWRITE].** <li> 
11650 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
11660 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
11670 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a  TE_OPEN_CREATE].
11680 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 7b  ** </ol>.**.** {
11690 46 31 32 37 31 31 7d 20 54 68 65 20 66 69 72 73  F12711} The firs
116a0 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68  t value opens th
116b0 65 20 64 61 74 61 62 61 73 65 20 72 65 61 64 2d  e database read-
116c0 6f 6e 6c 79 2e 20 0a 2a 2a 20 7b 46 31 32 37 31  only. .** {F1271
116d0 32 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  2} If the databa
116e0 73 65 20 64 6f 65 73 20 6e 6f 74 20 70 72 65 76  se does not prev
116f0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e  iously exist, an
11700 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
11710 65 64 2e 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20  ed..** {F12713} 
11720 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f  The second optio
11730 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64  n opens.** the d
11740 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
11750 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
11760 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
11770 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a  reading only if.
11780 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ** if the file i
11790 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
117a0 64 2e 20 20 7b 46 31 32 37 31 34 7d 20 49 6e 20  d.  {F12714} In 
117b0 65 69 74 68 65 72 20 63 61 73 65 20 74 68 65 20  either case the 
117c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 6d 75 73 74  database.** must
117d0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 20 6f   already exist o
117e0 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  r an error is re
117f0 74 75 72 6e 65 64 2e 20 20 7b 46 31 32 37 31 35  turned.  {F12715
11800 7d 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69  } The third opti
11810 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20  on.** opens the 
11820 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
11830 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
11840 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 20   and creates it 
11850 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
11860 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
11870 20 7b 46 31 32 37 31 36 7d 0a 2a 2a 20 54 68 65   {F12716}.** The
11880 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20 69   third options i
11890 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  s behavior that 
118a0 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
118b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
118c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
118d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
118e0 2a 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66  *.** {F12717} If
118f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
11900 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
11910 6e 20 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20  n an private.** 
11920 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
11930 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  se is created fo
11940 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
11950 2e 20 7b 46 31 32 37 31 38 7d 20 54 68 69 73 20  . {F12718} This 
11960 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74  in-memory.** dat
11970 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
11980 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  h when the datab
11990 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
119a0 73 20 63 6c 6f 73 65 64 2e 20 7b 45 4e 44 7d 20  s closed. {END} 
119b0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
119c0 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  on of SQLite mig
119d0 68 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ht make use of a
119e0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
119f0 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74  l filenames.** t
11a00 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
11a10 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
11a20 2e 20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  .  It is recomme
11a30 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68  nded that .** wh
11a40 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
11a50 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f  lename really do
11a60 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
11a70 20 22 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72   ":" that you pr
11a80 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
11a90 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
11aa0 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a  e like "./" to.*
11ab0 2a 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  * avoid ambiguit
11ac0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39  y..**.** {F12719
11ad0 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
11ae0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
11af0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
11b00 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a  vate temporary.*
11b10 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
11b20 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
11b30 65 64 2e 20 20 7b 46 31 32 37 32 30 7d 20 54 68  ed.  {F12720} Th
11b40 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
11b50 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
11b60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
11b70 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
11b80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
11b90 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
11ba0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 31  d..**.** {F12721
11bb0 7d 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  } The fourth par
11bc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
11bd0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
11be0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
11bf0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
11c00 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
11c10 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
11c20 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74  g system .** int
11c30 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
11c40 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
11c50 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
11c60 73 65 2e 20 20 7b 46 31 32 37 32 32 7d 20 49 66  se.  {F12722} If
11c70 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
11c80 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55  arameter is a NU
11c90 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
11ca0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
11cb0 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a  ite3_vfs].** obj
11cc0 65 63 74 20 69 73 20 75 73 65 64 2e 20 7b 45 4e  ect is used. {EN
11cd0 44 7d 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  D}.**.** <b>Note
11ce0 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72   to windows user
11cf0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
11d00 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
11d10 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
11d20 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74  ent.** of [sqlit
11d30 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
11d40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
11d50 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  )] must be UTF-8
11d60 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
11d70 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
11d80 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
11d90 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
11da0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
11db0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
11dc0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
11dd0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
11de0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
11df0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  hem into.** [sql
11e00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
11e10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
11e20 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
11e30 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
11e40 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
11e50 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
11e60 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
11e70 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
11e80 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
11e90 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
11ea0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
11eb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
11ec0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
11ed0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
11ee0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
11ef0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
11f00 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
11f10 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
11f20 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
11f30 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
11f40 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
11f50 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
11f60 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
11f70 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
11f80 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
11f90 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
11fa0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
11fb0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
11fc0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
11fd0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
11fe0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
11ff0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
12000 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
12010 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
12020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
12030 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
12040 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d 0a  ssages {F12800}.
12050 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54  **.** {F12801} T
12060 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
12070 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
12080 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
12090 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ic.** [SQLITE_OK
120a0 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20   | result code] 
120b0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
120c0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
120d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
120e0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
120f0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
12100 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
12110 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
12120 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64  h [sqlite3] hand
12130 6c 65 20 27 64 62 27 2e 20 7b 55 31 32 38 30 32  le 'db'. {U12802
12140 7d 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  } If a prior API
12150 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74   call failed but
12160 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
12170 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
12180 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
12190 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
121a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a  lite3_errcode().
121b0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
121c0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
121d0 32 38 30 33 7d 20 54 68 65 20 73 71 6c 69 74 65  2803} The sqlite
121e0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
121f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
12200 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
12210 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
12220 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
12230 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
12240 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54  ither UTF8 or UT
12250 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  F16 respectively
12260 2e 0a 2a 2a 20 7b 46 31 32 38 30 34 7d 20 4d 65  ..** {F12804} Me
12270 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
12280 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
12290 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
122a0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
122b0 7b 55 31 32 38 30 35 7d 20 54 68 65 20 0a 2a 2a  {U12805} The .**
122c0 20 73 74 72 69 6e 67 20 6d 61 79 20 62 65 20 6f   string may be o
122d0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
122e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 75 62  allocated by sub
122f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
12300 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72   SQLite.** inter
12310 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  face functions. 
12320 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  {END}.**.** {F12
12330 38 30 36 7d 20 43 61 6c 6c 73 20 74 6f 20 6d 61  806} Calls to ma
12340 6e 79 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e  ny sqlite3_* fun
12350 63 74 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65  ctions set the e
12360 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 0a 2a 2a  rror code and.**
12370 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
12380 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   by [sqlite3_err
12390 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  code()], [sqlite
123a0 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
123b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
123c0 6d 73 67 31 36 28 29 5d 20 6f 76 65 72 77 72 69  msg16()] overwri
123d0 74 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f 75  ting the previou
123e0 73 20 76 61 6c 75 65 73 2e 20 20 7b 46 31 32 38  s values.  {F128
123f0 30 37 7d 0a 2a 2a 20 45 78 63 65 70 74 2c 20 63  07}.** Except, c
12400 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
12410 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
12420 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
12430 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
12440 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 74 68 65  _errmsg16()] the
12450 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
12460 66 66 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 73  ffect the.** res
12470 75 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20 69  ults of future i
12480 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20 7b 46 31  nvocations.  {F1
12490 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41  2808} Calls to A
124a0 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  PI routines that
124b0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  .** do not retur
124c0 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  n an error code 
124d0 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74  (example: [sqlit
124e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
124f0 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e  ) do not.** chan
12500 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ge the error cod
12510 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
12520 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 7b 46 31  is routine.  {F1
12530 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73  2809} Interfaces
12540 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 6e 6f 74   that.** are not
12550 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
12560 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
12570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
12580 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 5b 73  (examples:.** [s
12590 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
125a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
125b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
125c0 65 28 29 5d 20 64 6f 20 6e 6f 74 20 63 68 61 6e  e()] do not chan
125d0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
125e0 20 63 6f 64 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a   code. {END}.**.
125f0 2a 2a 20 7b 46 31 32 38 31 30 7d 20 41 73 73 75  ** {F12810} Assu
12600 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69 6e  ming no other in
12610 74 65 72 76 65 6e 69 6e 67 20 73 71 6c 69 74 65  tervening sqlite
12620 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73 20 61 72  3_* API calls ar
12630 65 20 6d 61 64 65 2c 0a 2a 2a 20 74 68 65 20 65  e made,.** the e
12640 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e  rror code return
12650 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
12660 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
12670 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 0a  d with the same.
12680 2a 2a 20 65 72 72 6f 72 20 61 73 20 74 68 65 20  ** error as the 
12690 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
126a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   by [sqlite3_err
126b0 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  msg()] and [sqli
126c0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
126d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
126e0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
126f0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
12700 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
12710 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
12720 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
12730 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
12740 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
12750 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
12760 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30 30  nt Object {F1300
12770 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0}.**.** An inst
12780 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12790 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73 69  ect represent si
127a0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
127b0 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 62  nts.  This.** ob
127c0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
127d0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
127e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
127f0 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70  " or a .** "comp
12800 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
12810 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
12820 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
12830 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  ** .** The life 
12840 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
12850 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
12860 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
12870 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
12880 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
12890 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
128a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
128b0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
128c0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
128d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
128e0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
128f0 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a  ameters using.**
12900 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
12910 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
12920 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66  e3_bind_* interf
12930 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  aces]..** <li> R
12940 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
12950 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
12960 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
12970 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
12980 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
12990 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
129a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
129b0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
129c0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
129d0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
129e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
129f0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
12a00 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
12a10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
12a20 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
12a30 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
12a40 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
12a50 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
12a60 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
12a70 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
12a80 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
12a90 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
12aa0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
12ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12ac0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
12ad0 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  L Statement {F13
12ae0 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  010}.**.** To ex
12af0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
12b00 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
12b10 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
12b20 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
12b30 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
12b40 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
12b50 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46  tines. .**.** {F
12b60 31 33 30 31 31 7d 20 54 68 65 20 66 69 72 73 74  13011} The first
12b70 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69   argument "db" i
12b80 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c 20  s an [sqlite3 | 
12b90 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
12ba0 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61  handle] .** obta
12bb0 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
12bc0 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
12bd0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
12be0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a  ite3_open_v2()].
12bf0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
12c00 70 65 6e 31 36 28 29 5d 2e 20 7b 46 31 33 30 31  pen16()]. {F1301
12c10 32 7d 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  2}.** The second
12c20 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22   argument "zSql"
12c30 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
12c40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
12c50 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
12c60 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
12c70 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
12c80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
12c90 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
12ca0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
12cb0 66 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38  faces uses UTF-8
12cc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
12cd0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
12ce0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
12cf0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
12d00 36 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  6. {END}.**.** {
12d10 46 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e  F13013} If the n
12d20 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
12d30 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65   less.** than ze
12d40 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
12d50 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
12d60 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
12d70 6e 61 74 6f 72 2e 0a 2a 2a 20 7b 46 31 33 30 31  nator..** {F1301
12d80 34 7d 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  4} If nByte is n
12d90 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
12da0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
12db0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  mum number of .*
12dc0 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  * bytes read fro
12dd0 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
12de0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
12df0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
12e00 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
12e10 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
12e20 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
12e30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
12e40 20 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e   .** until the n
12e50 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
12e60 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
12e70 72 73 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  rst. {END}.**.**
12e80 20 7b 46 31 33 30 31 35 7d 20 2a 70 7a 54 61 69   {F13015} *pzTai
12e90 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
12ea0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
12eb0 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
12ec0 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  d of the.** firs
12ed0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
12ee0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
12ef0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f  routines only co
12f00 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72 73 74  mpiles the first
12f10 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
12f20 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
12f30 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
12f40 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
12f50 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64  ns.** uncompiled
12f60 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
12f70 31 33 30 31 36 7d 20 2a 70 70 53 74 6d 74 20 69  13016} *ppStmt i
12f80 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
12f90 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a  to a compiled .*
12fa0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
12fb0 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
12fc0 73 74 72 75 63 74 75 72 65 5d 20 74 68 61 74 20  structure] that 
12fd0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
12fe0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
12ff0 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69  3_step()].  Or i
13000 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
13010 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79  ror, *ppStmt may
13020 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55   be.** set to NU
13030 4c 4c 2e 20 20 7b 46 31 33 30 31 37 7d 20 49 66  LL.  {F13017} If
13040 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
13050 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
13060 28 69 66 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a  (if the input.**
13070 20 69 73 20 61 6e 64 20 65 6d 70 74 79 20 73 74   is and empty st
13080 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
13090 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
130a0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
130b0 2a 2a 20 7b 55 31 33 30 31 38 7d 20 54 68 65 20  ** {U13018} The 
130c0 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
130d0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
130e0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
130f0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51  e.** compiled SQ
13100 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75  L statement.** u
13110 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
13120 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
13130 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
13140 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 7b  with it..**.** {
13150 46 31 33 30 31 39 7d 20 4f 6e 20 73 75 63 63 65  F13019} On succe
13160 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
13170 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
13180 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b  herwise an .** [
13190 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
131a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
131b0 74 75 72 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  turned. {END}.**
131c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
131d0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
131e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
131f0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
13200 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
13210 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
13220 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
13230 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
13240 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
13250 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
13260 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
13270 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
13280 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
13290 2a 2a 20 7b 46 31 33 30 32 30 7d 20 49 6e 20 74  ** {F13020} In t
132a0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
132b0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
132c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
132d0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
132e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
132f0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
13300 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
13310 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  e .** original S
13320 51 4c 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54  QL text. {END} T
13330 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
13340 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
13350 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
13360 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65  behave a differe
13370 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73  ntly in two ways
13380 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
13390 3c 6c 69 3e 7b 46 31 33 30 32 32 7d 0a 2a 2a 20  <li>{F13022}.** 
133a0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
133b0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
133c0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
133d0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
133e0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
133f0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
13400 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
13410 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
13420 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
13430 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
13440 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
13450 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 7b 46 31  un it again. {F1
13460 32 30 32 33 7d 20 49 66 20 74 68 65 20 73 63 68  2023} If the sch
13470 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20  ema has changed 
13480 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74  in.** a way that
13490 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65   makes the state
134a0 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76  ment no longer v
134b0 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  alid, [sqlite3_s
134c0 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c  tep()] will stil
134d0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
134e0 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 7b 45  ITE_SCHEMA].  {E
134f0 4e 44 7d 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ND} But unlike t
13500 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
13510 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  or, .** [SQLITE_
13520 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61  SCHEMA] is now a
13530 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 7b   fatal error.  {
13540 46 31 32 30 32 34 7d 20 43 61 6c 6c 69 6e 67 0a  F12024} Calling.
13550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
13560 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20  are_v2()] again 
13570 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68  will not make th
13580 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77  e.** error go aw
13590 61 79 2e 20 20 7b 46 31 32 30 32 35 7d 20 4e 6f  ay.  {F12025} No
135a0 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
135b0 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
135c0 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
135d0 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
135e0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
135f0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
13600 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b  CHEMA] return. {
13610 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  END}.** </li>.**
13620 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 7b 46 31 33  .** <li>.** {F13
13630 30 33 30 7d 20 57 68 65 6e 20 61 6e 20 65 72 72  030} When an err
13640 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b  or occurs, .** [
13650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
13660 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
13670 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 20  of the detailed 
13680 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
13690 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  R | result codes
136a0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
136b0 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
136c0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
136d0 65 73 5d 2e 20 20 7b 46 31 33 30 33 31 7d 0a 2a  es].  {F13031}.*
136e0 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68  * The legacy beh
136f0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 20 5b  avior was that [
13700 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
13710 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
13720 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b  n a generic.** [
13730 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
13740 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20 79 6f  sult code and yo
13750 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
13760 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
13770 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13780 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
13790 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
137a0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
137b0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
137c0 0a 2a 2a 20 7b 46 31 33 30 33 32 7d 0a 2a 2a 20  .** {F13032}.** 
137d0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
137e0 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73  epare interfaces
137f0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
13800 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
13810 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75  error is.** retu
13820 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
13830 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e  . {END}.** </li>
13840 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
13850 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
13860 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
13870 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
13880 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
13890 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
138a0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
138b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
138c0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
138d0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
138e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
138f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
13900 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
13910 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
13920 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
13930 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
13940 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
13950 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
13960 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
13970 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
13980 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
13990 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
139a0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
139b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
139c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
139d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
139e0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
139f0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
13a00 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
13a10 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
13a20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
13a30 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
13a40 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
13a50 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
13a60 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
13a70 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
13a80 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
13a90 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
13aa0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
13ab0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
13ac0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
13ad0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
13ae0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
13af0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
13b00 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
13b10 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
13b20 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
13b30 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
13b40 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
13b50 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
13b60 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
13b70 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
13b80 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
13b90 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
13ba0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
13bb0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
13bc0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
13bd0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
13be0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
13bf0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
13c00 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
13c10 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
13c20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
13c30 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
13c40 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
13c50 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
13c60 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
13c70 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
13c80 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
13c90 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
13ca0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
13cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
13cc0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
13cd0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
13ce0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
13cf0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
13d00 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
13d10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
13d20 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
13d30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
13d40 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
13d50 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
13d60 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
13d70 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
13d80 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46  Statement SQL {F
13d90 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  13100}.**.** {F1
13da0 33 31 30 31 7d 20 49 66 20 74 68 65 20 63 6f 6d  3101} If the com
13db0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
13dc0 65 6e 74 20 70 61 73 73 65 64 20 61 73 20 61 6e  ent passed as an
13dd0 20 61 72 67 75 6d 65 6e 74 20 77 61 73 0a 2a 2a   argument was.**
13de0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
13df0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
13e00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
13e10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13e20 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 74 68  e16_v2()],.** th
13e30 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  en this function
13e40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
13e50 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
13e60 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 0a 2a  minated string.*
13e70 2a 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 63  * containing a c
13e80 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
13e90 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  nal SQL statemen
13ea0 74 2e 20 7b 46 31 33 31 30 32 7d 20 54 68 65 0a  t. {F13102} The.
13eb0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ** pointer is va
13ec0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 73 74  lid until the st
13ed0 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 73 20 64 65  atement.** is de
13ee0 6c 65 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  leted using sqli
13ef0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 2e 0a  te3_finalize()..
13f00 2a 2a 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20  ** {F13103} The 
13f10 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
13f20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  by sqlite3_sql()
13f30 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 38 20   is always UTF8 
13f40 65 76 65 6e 0a 2a 2a 20 69 66 20 61 20 55 54 46  even.** if a UTF
13f50 31 36 20 73 74 72 69 6e 67 20 77 61 73 20 6f 72  16 string was or
13f60 69 67 69 6e 61 6c 6c 79 20 65 6e 74 65 72 65 64  iginally entered
13f70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
13f80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 0a  prepare16_v2()].
13f90 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
13fa0 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lent..**.** {F13
13fb0 31 30 34 7d 20 49 66 20 74 68 65 20 73 74 61 74  104} If the stat
13fc0 65 6d 65 6e 74 20 77 61 73 20 63 6f 6d 70 69 6c  ement was compil
13fd0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
13fe0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
13ff0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
14000 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
14010 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
14020 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 0a 2a  are16()], this.*
14030 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  * function retur
14040 6e 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73  ns NULL..*/.cons
14050 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
14060 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
14070 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
14080 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61   CAPI3REF:  Dyna
14090 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
140a0 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35  lue Object  {F15
140b0 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 30  000}.**.** {F150
140c0 30 31 7d 20 53 51 4c 69 74 65 20 75 73 65 73 20  01} SQLite uses 
140d0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
140e0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
140f0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
14100 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 6f 72 20  .** that are or 
14110 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
14120 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
14130 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 53 51 4c 69  e. {END}.** SQLi
14140 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
14150 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76  typing for the v
14160 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
14170 20 20 0a 2a 2a 20 7b 46 31 35 30 30 32 7d 20 56    .** {F15002} V
14180 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
14190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
141a0 6a 65 63 74 73 20 63 61 6e 20 62 65 0a 2a 2a 20  jects can be.** 
141b0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
141c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
141d0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
141e0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2f 0a  Bs, or NULL..*/.
141f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
14200 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
14210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14220 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  F:  SQL Function
14230 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
14240 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54  {F16001}.**.** T
14250 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
14260 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
14270 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
14280 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
14290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
142a0 6f 62 6a 65 63 74 2e 20 20 7b 46 31 36 30 30 32  object.  {F16002
142b0 7d 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  } A pointer to a
142c0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
142d0 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 61  t.** object is a
142e0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
142f0 6d 65 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  meter to applica
14300 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
14310 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74   functions..*/.t
14320 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
14330 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
14340 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
14350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14360 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
14370 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
14380 65 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a  ements {F13500}.
14390 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 31 7d 20 49  **.** {F13501} I
143a0 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
143b0 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
143c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
143d0 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72  ] and its.** var
143e0 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73 20  iants, literals 
143f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20 62  may be replace b
14400 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e  y a parameter in
14410 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65   one.** of these
14420 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
14430 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
14440 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
14450 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c 69  li>  :AAA.** <li
14460 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20  >  @AAA.** <li> 
14470 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
14480 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
14490 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
144a0 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
144b0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
144c0 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e 20  l,.** AAA is an 
144d0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
144e0 6e 74 69 66 69 65 72 20 61 6e 64 20 56 56 56 20  ntifier and VVV 
144f0 69 73 20 61 20 76 61 72 69 61 62 6c 65 20 6e 61  is a variable na
14500 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20  me according.** 
14510 74 6f 20 74 68 65 20 73 79 6e 74 61 78 20 72 75  to the syntax ru
14520 6c 65 73 20 6f 66 20 74 68 65 20 54 43 4c 20 70  les of the TCL p
14530 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75  rogramming langu
14540 61 67 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68  age. {END}.** Th
14550 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
14560 65 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  e parameters (al
14570 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
14580 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
14590 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
145a0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
145b0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
145c0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
145d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 32 7d  ..**.** {F13502}
145e0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
145f0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
14600 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
14610 69 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69  ines always.** i
14620 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
14630 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
14640 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
14650 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
14660 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14670 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
14680 2e 20 20 7b 46 31 33 35 30 33 7d 20 54 68 65 20  .  {F13503} The 
14690 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
146a0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
146b0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
146c0 20 74 6f 20 62 65 20 73 65 74 2e 20 20 7b 46 31   to be set.  {F1
146d0 33 35 30 34 7d 20 54 68 65 0a 2a 2a 20 66 69 72  3504} The.** fir
146e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
146f0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
14700 20 7b 46 31 33 35 30 35 7d 20 57 68 65 6e 20 74   {F13505} When t
14710 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
14720 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
14730 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
14740 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
14750 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
14760 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
14770 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
14780 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
14790 6e 63 65 2e 20 0a 2a 2a 20 7b 46 31 33 35 30 36  nce. .** {F13506
147a0 7d 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  } The index for 
147b0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
147c0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
147d0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
147e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
147f0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41  ameter_name()] A
14800 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
14810 7b 46 31 33 35 30 37 7d 20 54 68 65 20 69 6e 64  {F13507} The ind
14820 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
14830 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
14840 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
14850 0a 2a 2a 20 7b 46 31 33 35 30 38 7d 20 54 68 65  .** {F13508} The
14860 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
14870 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
14880 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
14890 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 53  e.** parameter S
148a0 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
148b0 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61 75  LE_NUMBER (defau
148c0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 20  lt value: 999). 
148d0 7b 45 4e 44 7d 0a 2a 2a 20 53 65 65 20 3c 61 20  {END}.** See <a 
148e0 68 72 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74 6d  href="limits.htm
148f0 6c 22 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f  l">limits.html</
14900 61 3e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  a> for additiona
14910 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
14920 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68  *.** {F13509} Th
14930 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
14940 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
14950 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
14960 61 6d 65 74 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a  ameter. {END}.**
14970 0a 2a 2a 20 7b 46 31 33 35 31 30 7d 20 49 6e 20  .** {F13510} In 
14980 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  those.** routine
14990 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
149a0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
149b0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  ts value is the 
149c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
149d0 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ** in the parame
149e0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
149f0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
14a00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
14a10 74 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74  tes in the.** st
14a20 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
14a30 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
14a40 72 73 2e 20 7b 46 31 33 35 31 31 7d 20 20 54 68  rs. {F13511}  Th
14a50 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
14a60 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ytes does not in
14a70 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74  clude the zero-t
14a80 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
14a90 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e   end of strings.
14aa0 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 0a 2a 2a 20  .** {F13512}.** 
14ab0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
14ac0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
14ad0 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
14ae0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
14af0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
14b00 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
14b10 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
14b20 74 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  tor. {END}.**.**
14b30 20 7b 46 31 33 35 31 33 7d 0a 2a 2a 20 54 68 65   {F13513}.** The
14b40 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
14b50 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
14b60 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
14b70 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
14b80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
14b90 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
14ba0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
14bb0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
14bc0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74   BLOB or.** text
14bd0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
14be0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
14bf0 69 74 2e 20 7b 46 31 33 35 31 34 7d 20 49 66 20  it. {F13514} If 
14c00 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
14c10 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
14c20 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
14c30 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
14c40 20 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73   the library ass
14c50 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
14c60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
14c70 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
14c80 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
14c90 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
14ca0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 7b 46 31  be freed..** {F1
14cb0 33 35 31 35 7d 20 49 66 20 74 68 65 20 66 69 66  3515} If the fif
14cc0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
14cd0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
14ce0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
14cf0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
14d00 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
14d10 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
14d20 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
14d30 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
14d40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
14d50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
14d60 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
14d70 33 35 32 30 7d 20 54 68 65 20 73 71 6c 69 74 65  3520} The sqlite
14d80 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
14d90 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
14da0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
14db0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
14dc0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e  lled with zeros.
14dd0 20 20 7b 46 31 33 35 32 31 7d 20 41 20 7a 65 72    {F13521} A zer
14de0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
14df0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
14e00 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
14e10 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
14e20 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  it size) while i
14e30 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
14e40 73 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 5a  ssed. {END}.** Z
14e50 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
14e60 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
14e70 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20  s place-holders 
14e80 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
14e90 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
14ea0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
14eb0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  g .** [sqlite3_b
14ec0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
14ed0 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ment BLOB I/O] r
14ee0 6f 75 74 69 6e 65 73 2e 20 7b 46 31 33 35 32 32  outines. {F13522
14ef0 7d 20 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20  } A negative.** 
14f00 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
14f10 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
14f20 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
14f30 42 4c 4f 42 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  BLOB. {END}.**.*
14f40 2a 20 7b 46 31 33 35 33 30 7d 20 54 68 65 20 73  * {F13530} The s
14f50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
14f60 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
14f70 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a   called after.**
14f80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14f90 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73  e_v2()] (and its
14fa0 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73   variants) or [s
14fb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
14fc0 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73  and.** before [s
14fd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
14fe0 7b 46 31 33 35 33 31 7d 0a 2a 2a 20 42 69 6e 64  {F13531}.** Bind
14ff0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
15000 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
15010 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
15020 75 74 69 6e 65 2e 0a 2a 2a 20 7b 46 31 33 35 33  utine..** {F1353
15030 32 7d 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  2} Unbound param
15040 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
15050 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 20 7b  reted as NULL. {
15060 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  END}.**.** {F135
15070 34 30 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e  40} These routin
15080 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
15090 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
150a0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
150b0 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
150c0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 7b 46   goes wrong.  {F
150d0 31 33 35 34 31 7d 20 5b 53 51 4c 49 54 45 5f 52  13541} [SQLITE_R
150e0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
150f0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
15100 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
15110 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 7b 46  ut of range.  {F
15120 31 33 35 34 32 7d 20 5b 53 51 4c 49 54 45 5f 4e  13542} [SQLITE_N
15130 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
15140 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c  d if malloc fail
15150 73 2e 0a 2a 2a 20 7b 46 31 33 35 34 33 7d 20 5b  s..** {F13543} [
15160 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 69  SQLITE_MISUSE] i
15170 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
15180 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
15190 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
151a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
151b0 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
151c0 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
151d0 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
151e0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a  n finalized..*/.
151f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
15200 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
15210 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
15220 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
15230 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
15240 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
15250 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
15260 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
15270 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
15280 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
15290 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
152a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
152b0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
152c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
152d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
152e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
152f0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
15300 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
15310 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
15320 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
15330 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
15340 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
15350 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
15360 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
15370 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
15380 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
15390 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
153a0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
153b0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
153c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
153d0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
153e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
153f0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
15400 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
15410 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
15420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15430 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50  Number Of Host P
15440 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36 30  arameters {F1360
15450 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31  0}.**.** {F13601
15460 7d 20 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72  } Return the lar
15470 67 65 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  gest host parame
15480 74 65 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65  ter index in the
15490 20 70 72 65 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   precompiled.** 
154a0 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65 6e 20  statement given 
154b0 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e  as the argument.
154c0 20 7b 46 31 33 36 30 32 7d 20 57 68 65 6e 20 74   {F13602} When t
154d0 68 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  he host paramete
154e0 72 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65  rs.** are of the
154f0 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41 41   forms like ":AA
15500 41 22 2c 20 22 24 56 56 56 22 2c 20 22 40 41 41  A", "$VVV", "@AA
15510 41 22 2c 20 6f 72 20 22 3f 22 2c 0a 2a 2a 20 74  A", or "?",.** t
15520 68 65 6e 20 74 68 65 79 20 61 72 65 20 61 73 73  hen they are ass
15530 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69 61 6c  igned sequential
15540 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d 62   increasing numb
15550 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ers beginning.**
15560 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68   with one, so th
15570 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15580 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
15590 66 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  f parameters..**
155a0 20 7b 46 31 33 36 30 33 7d 20 48 6f 77 65 76 65   {F13603} Howeve
155b0 72 0a 2a 2a 20 69 66 20 74 68 65 20 73 61 6d 65  r.** if the same
155c0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
155d0 6e 61 6d 65 20 69 73 20 75 73 65 64 20 6d 75 6c  name is used mul
155e0 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 65 61 63  tiple times, eac
155f0 68 20 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20  h occurrance.** 
15600 69 73 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  is given the sam
15610 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20 74 68 65  e number, so the
15620 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
15630 69 6e 20 74 68 61 74 20 63 61 73 65 20 69 73 20  in that case is 
15640 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
15650 20 75 6e 69 71 75 65 20 68 6f 73 74 20 70 61 72   unique host par
15660 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e 20 7b 46  ameter names. {F
15670 31 33 36 30 34 7d 20 49 66 20 68 6f 73 74 20 70  13604} If host p
15680 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
15690 0a 2a 2a 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  .** form "?NNN" 
156a0 61 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20  are used (where 
156b0 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
156c0 72 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69  r) then there mi
156d0 67 68 74 20 62 65 0a 2a 2a 20 67 61 70 73 20 69  ght be.** gaps i
156e0 6e 20 74 68 65 20 6e 75 6d 62 65 72 69 6e 67 20  n the numbering 
156f0 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65  and the value re
15700 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69  turned by this i
15710 6e 74 65 72 66 61 63 65 20 69 73 0a 2a 2a 20 74  nterface is.** t
15720 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
15730 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77  host parameter w
15740 69 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20  ith the largest 
15750 69 6e 64 65 78 20 76 61 6c 75 65 2e 20 7b 45 4e  index value. {EN
15760 44 7d 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 36 30 35  D}.**.** {U13605
15770 7d 20 54 68 65 20 70 72 65 70 61 72 65 64 20 73  } The prepared s
15780 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e 6f  tatement must no
15790 74 20 62 65 20 5b 73 71 6c 69 74 65 33 5f 66 69  t be [sqlite3_fi
157a0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
157b0 65 64 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ed].** prior to 
157c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
157d0 75 72 6e 69 6e 67 2e 20 20 4f 74 68 65 72 77 69  urning.  Otherwi
157e0 73 65 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  se the results a
157f0 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20  re undefined.** 
15800 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
15810 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74  esirable..*/.int
15820 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
15830 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
15840 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
15850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
15860 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
15870 72 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d  rameter {F13620}
15880 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20  .**.** {F13621} 
15890 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
158a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
158b0 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  o the name of th
158c0 65 20 6e 2d 74 68 0a 2a 2a 20 70 61 72 61 6d 65  e n-th.** parame
158d0 74 65 72 20 69 6e 20 61 20 5b 73 71 6c 69 74 65  ter in a [sqlite
158e0 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
158f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 7b 46  d statement]. {F
15900 31 33 36 32 32 7d 0a 2a 2a 20 48 6f 73 74 20 70  13622}.** Host p
15910 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
15920 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20   form ":AAA" or 
15930 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 22  "@AAA" or "$VVV"
15940 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20   have a name.** 
15950 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
15960 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40  ing ":AAA" or "@
15970 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20  AAA" or "$VVV". 
15980 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
15990 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
159a0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
159b0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
159c0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
159d0 6e 61 6d 65 2e 20 20 7b 46 31 33 36 32 36 7d 0a  name.  {F13626}.
159e0 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
159f0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72   the form "?" or
15a00 20 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20   "?NNN" have no 
15a10 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  name..**.** {F13
15a20 36 32 33 7d 20 54 68 65 20 66 69 72 73 74 20 68  623} The first h
15a30 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
15a40 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
15a50 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46   not 0..**.** {F
15a60 31 33 36 32 34 7d 20 49 66 20 74 68 65 20 76 61  13624} If the va
15a70 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
15a80 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
15a90 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
15aa0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
15ab0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
15ac0 72 6e 65 64 2e 20 20 7b 46 31 33 36 32 35 7d 20  rned.  {F13625} 
15ad0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
15ae0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
15af0 20 69 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e   in the UTF-8 en
15b00 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
15b10 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
15b20 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
15b30 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
15b40 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
15b50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
15b60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
15b70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
15b80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
15b90 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
15ba0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
15bb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
15bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15bd0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
15be0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
15bf0 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36 34  iven Name {F1364
15c00 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31  0}.**.** {F13641
15c10 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  } This routine r
15c20 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
15c30 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d   of a host param
15c40 65 74 65 72 20 77 69 74 68 20 74 68 65 0a 2a 2a  eter with the.**
15c50 20 67 69 76 65 6e 20 6e 61 6d 65 2e 20 20 7b 46   given name.  {F
15c60 31 33 36 34 32 7d 20 54 68 65 20 6e 61 6d 65 20  13642} The name 
15c70 6d 75 73 74 20 6d 61 74 63 68 20 65 78 61 63 74  must match exact
15c80 6c 79 2e 20 20 7b 46 31 33 36 34 33 7d 0a 2a 2a  ly.  {F13643}.**
15c90 20 49 66 20 6e 6f 20 70 61 72 61 6d 65 74 65 72   If no parameter
15ca0 20 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20   with the given 
15cb0 6e 61 6d 65 20 69 73 20 66 6f 75 6e 64 2c 20 72  name is found, r
15cc0 65 74 75 72 6e 20 30 2e 0a 2a 2a 20 7b 46 31 33  eturn 0..** {F13
15cd0 36 34 34 7d 20 50 61 72 61 6d 65 74 65 72 20 6e  644} Parameter n
15ce0 61 6d 65 73 20 6d 75 73 74 20 62 65 20 55 54 46  ames must be UTF
15cf0 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  8..*/.int sqlite
15d00 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
15d10 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
15d20 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
15d30 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
15d40 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
15d50 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
15d60 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
15d70 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a  ement {F13660}.*
15d80 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20 43 6f  *.** {F13661} Co
15d90 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
15da0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
15db0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
15dc0 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72  )] does not.** r
15dd0 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65  eset the [sqlite
15de0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
15df0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a  ndings] on a .**
15e00 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
15e10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
15e20 65 6e 74 5d 2e 20 7b 46 31 33 36 36 32 7d 20 55  ent]. {F13662} U
15e30 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
15e40 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20  to.** reset all 
15e50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
15e60 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
15e70 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
15e80 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
15e90 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
15ea0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
15eb0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
15ec0 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31  esult Set {F1371
15ed0 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31  0}.**.** {F13711
15ee0 7d 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  } Return the num
15ef0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
15f00 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
15f10 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
15f20 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
15f30 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
15f40 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 7b 46  L statement]. {F
15f50 31 33 37 31 32 7d 20 54 68 69 73 20 72 6f 75 74  13712} This rout
15f60 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a  ine returns 0.**
15f70 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
15f80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
15f90 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
15fa0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a  rn data (for .**
15fb0 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41   example an UPDA
15fc0 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  TE)..*/.int sqli
15fd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
15fe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
15ff0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
16000 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
16010 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
16020 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a   Set {F13720}.**
16030 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20 54 68 65  .** {F13721} The
16040 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
16050 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
16060 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
16070 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
16080 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
16090 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
160a0 74 65 6d 65 6e 74 2e 20 20 7b 46 31 33 37 32 32  tement.  {F13722
160b0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  } The sqlite3_co
160c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
160d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
160e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
160f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
16100 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  UTF8 string.** a
16110 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
16120 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
16130 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
16140 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
16150 64 0a 2a 2a 20 55 54 46 31 36 20 73 74 72 69 6e  d.** UTF16 strin
16160 67 2e 20 7b 46 31 33 37 32 33 7d 20 20 54 68 65  g. {F13723}  The
16170 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16180 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   is the.** [sqli
16190 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
161a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
161b0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
161c0 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  he SELECT statem
161d0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ent..** The seco
161e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
161f0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  the column numbe
16200 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73  r.  The left-mos
16210 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e  t column is.** n
16220 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b  umber 0..**.** {
16230 46 31 33 37 32 34 7d 20 54 68 65 20 72 65 74 75  F13724} The retu
16240 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
16250 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
16260 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a  il either the .*
16270 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
16280 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
16290 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
162a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
162b0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72  inalize()].** or
162c0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
162d0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
162e0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
162f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
16300 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20  e16().** on the 
16310 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
16320 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 73  ** {F13725} If s
16330 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16340 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
16350 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
16360 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
16370 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
16380 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
16390 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
163a0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
163b0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
163c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 63  s returned..*/.c
163d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
163e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
163f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
16400 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
16410 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
16420 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
16430 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
16440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16450 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
16460 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
16470 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13740}.**.** 
16480 7b 46 31 33 37 34 31 7d 20 54 68 65 73 65 20 72  {F13741} These r
16490 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
164a0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
164b0 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
164c0 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
164d0 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
164e0 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
164f0 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
16500 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
16510 2a 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20 6e  * {F13742} The n
16520 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
16530 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
16540 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
16550 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
16560 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54  her a UTF8 or UT
16570 46 31 36 20 73 74 72 69 6e 67 2e 20 20 7b 46 31  F16 string.  {F1
16580 33 37 34 33 7d 20 54 68 65 20 5f 64 61 74 61 62  3743} The _datab
16590 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
165a0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
165b0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
165c0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
165d0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
165e0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
165f0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
16600 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
16610 6c 75 6d 6e 20 6e 61 6d 65 2e 20 7b 46 31 33 37  lumn name. {F137
16620 34 34 7d 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  44}.** The retur
16630 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
16640 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65  lid until.** the
16650 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
16660 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
16670 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
16680 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
16690 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
166a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
166b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
166c0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
166d0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
166e0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
166f0 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54 68 65 20  ** {F13745} The 
16700 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
16710 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
16720 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
16730 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
16740 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
16750 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  column..**.** {F
16760 31 33 37 34 36 7d 20 54 68 65 20 66 69 72 73 74  13746} The first
16770 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
16780 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
16790 20 69 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   is a .** [sqlit
167a0 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
167b0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
167c0 5d 2e 0a 2a 2a 20 7b 46 31 33 37 34 37 7d 20 54  ]..** {F13747} T
167d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
167e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
167f0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
16800 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
16810 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65  by .** the state
16820 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
16830 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
16840 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
16850 2a 0a 2a 2a 20 7b 46 31 33 37 34 38 7d 20 49 66  *.** {F13748} If
16860 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
16870 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
16880 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
16890 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72  expression.** or
168a0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
168b0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
168c0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
168d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
168e0 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  .** return NULL.
168f0 20 20 7b 46 31 33 37 34 39 7d 20 4f 74 68 65 72    {F13749} Other
16900 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
16910 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f  n the .** name o
16920 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
16930 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61  atabase, table a
16940 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  nd column that q
16950 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63  uery result.** c
16960 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
16970 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
16980 7b 46 31 33 37 35 30 7d 20 41 73 20 77 69 74 68  {F13750} As with
16990 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
169a0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f  e APIs, those po
169b0 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36  stfixed with "16
169c0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
169d0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
169e0 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75  gs, the other fu
169f0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
16a00 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  TF-8. {END}.**.*
16a10 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
16a20 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
16a30 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
16a40 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
16a50 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
16a60 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
16a70 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
16a80 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
16a90 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35  ed..**.** {U1375
16aa0 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  1}.** If two or 
16ab0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
16ac0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
16ad0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
16ae0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
16af0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
16b00 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
16b10 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
16b20 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
16b30 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
16b40 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
16b50 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
16b60 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
16b70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
16b80 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
16b90 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
16ba0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
16bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
16bc0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
16bd0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
16be0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
16bf0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
16c00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
16c10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
16c20 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
16c30 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
16c40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
16c50 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
16c60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
16c70 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
16c80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
16c90 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
16ca0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
16cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16cc0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
16cd0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
16ce0 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d   Result {F13760}
16cf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
16d00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
16d10 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
16d20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
16d30 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 7b 46 31  tement]. .** {F1
16d40 33 37 36 31 7d 20 49 66 20 74 68 69 73 20 73 74  3761} If this st
16d50 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c  atement is a SEL
16d60 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  ECT statement an
16d70 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
16d80 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75   of the .** retu
16d90 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
16da0 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69  of that SELECT i
16db0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
16dc0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
16dd0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
16de0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
16df0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
16e00 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
16e10 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  n is returned.  
16e20 7b 46 31 33 37 36 32 7d 20 49 66 20 74 68 65 20  {F13762} If the 
16e30 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
16e40 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
16e50 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
16e60 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
16e70 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
16e80 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
16e90 2a 20 7b 46 31 33 37 36 33 7d 20 54 68 65 20 72  * {F13763} The r
16ea0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
16eb0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
16ec0 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a  ncoded.  {END} .
16ed0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
16ee0 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
16ef0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
16f00 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
16f10 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
16f20 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   And the followi
16f30 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  ng statement com
16f40 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
16f50 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
16f60 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68  ROM t1;.**.** Th
16f70 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
16f80 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
16f90 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
16fa0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
16fb0 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  .** result colum
16fc0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
16fd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
16fe0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
16ff0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d  t column.** (i==
17000 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
17010 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
17020 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
17030 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
17040 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
17050 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
17060 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
17070 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
17080 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
17090 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
170a0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
170b0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
170c0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
170d0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
170e0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
170f0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
17100 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
17110 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
17120 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
17130 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
17140 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
17150 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
17160 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
17170 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
17180 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
17190 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  pe(sqlite3_stmt 
171a0 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f 6e 73 74  *, int i);.const
171b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
171c0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
171d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
171e0 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50  nt);../* .** CAP
171f0 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65  I3REF:  Evaluate
17200 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
17210 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13200}.**.**
17220 20 41 66 74 65 72 20 61 6e 20 5b 73 71 6c 69 74   After an [sqlit
17230 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74  e3_stmt | SQL st
17240 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
17250 6e 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20  n prepared with 
17260 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74  a call.** to eit
17270 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
17280 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
17290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
172a0 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65  _v2()] or to one
172b0 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63   of.** the legac
172c0 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
172d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
172e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
172f0 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68  pare16()],.** th
17300 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  en this function
17310 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
17320 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
17330 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
17340 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  e .** statement.
17350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
17360 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
17370 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74  or of this sqlit
17380 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
17390 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
173a0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
173b0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
173c0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
173d0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
173e0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
173f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
17400 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17410 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
17420 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
17430 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
17440 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
17450 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
17460 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
17470 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
17480 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
17490 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
174a0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
174b0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
174c0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
174d0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
174e0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
174f0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61  *.** In the laga
17500 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
17510 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
17520 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
17530 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a  QLITE_BUSY], .**
17540 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
17550 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
17560 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
17570 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
17580 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
17590 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
175a0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
175b0 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
175c0 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b  lt code].** or [
175d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
175e0 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
175f0 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20  ult code] might 
17600 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
17610 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  * well..**.** [S
17620 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
17630 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
17640 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
17650 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
17660 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
17670 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
17680 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
17690 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
176a0 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20   is a COMMIT.** 
176b0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
176c0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
176d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
176e0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
176f0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
17700 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
17710 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f  ment is not a CO
17720 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20  MMIT and occurs 
17730 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
17740 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
17750 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
17760 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
17770 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
17780 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
17790 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  **.** [SQLITE_DO
177a0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
177b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
177c0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
177d0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
177e0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
177f0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
17800 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
17810 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
17820 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
17830 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
17840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
17850 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
17860 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
17870 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
17880 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
17890 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
178a0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
178b0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
178c0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a  any data, then .
178d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ** [SQLITE_ROW] 
178e0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
178f0 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
17900 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
17910 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69  .** for processi
17920 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ng by the caller
17930 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
17940 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
17950 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
17960 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
17970 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
17980 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
17990 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
179a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
179b0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
179c0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
179d0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
179e0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
179f0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
17a00 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
17a10 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
17a20 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
17a30 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
17a40 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
17a50 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
17a60 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
17a70 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
17a80 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
17a90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
17aa0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
17ab0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
17ac0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
17ad0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
17ae0 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53   (example:.** [S
17af0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
17b00 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
17b10 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
17b20 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
17b30 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
17b40 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
17b50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
17b60 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 73 71  )] on the.** [sq
17b70 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
17b80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
17b90 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  .  In the "v2" i
17ba0 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
17bb0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
17bc0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
17bd0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
17be0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
17bf0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
17c00 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
17c10 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
17c20 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
17c30 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
17c40 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
17c50 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 73  s called on a [s
17c60 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
17c70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
17c80 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
17c90 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
17ca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
17cb0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
17cc0 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a  one that had .**
17cd0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
17ce0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
17cf0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
17d00 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
17d10 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
17d20 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
17d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17d40 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
17d50 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
17d60 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
17d70 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
17d80 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n time..**.** <b
17d90 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
17da0 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49   Alert:</b>.** I
17db0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
17dc0 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20  erface, .** the 
17dd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41  sqlite3_step() A
17de0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
17df0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
17e00 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49  r code,.** [SQLI
17e10 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
17e20 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f  wing any error o
17e30 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
17e40 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b  E_BUSY].** and [
17e50 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
17e60 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b   You must call [
17e70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
17e80 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
17e90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
17ea0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
17eb0 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63   of the specific
17ec0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
17ed0 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  R | result codes
17ee0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
17ef0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
17f00 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
17f10 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
17f20 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
17f30 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
17f40 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
17f50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
17f60 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
17f70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
17f80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
17f90 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
17fa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17fb0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
17fc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
17fd0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
17fe0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
17ff0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
18000 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
18010 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74  are16()], then t
18020 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63  he .** more spec
18030 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  ific [SQLITE_ERR
18040 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OR | result code
18050 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
18060 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
18070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
18080 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
18090 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
180a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
180b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
180c0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
180d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
180e0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
180f0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
18100 20 73 65 74 20 7b 46 31 33 37 37 30 7d 0a 2a 2a   set {F13770}.**
18110 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
18120 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
18130 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
18140 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
18150 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33   set..**.** {F13
18160 37 37 31 7d 20 41 66 74 65 72 20 61 20 63 61 6c  771} After a cal
18170 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
18180 65 70 28 29 5d 20 74 68 61 74 20 72 65 74 75 72  ep()] that retur
18190 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ns [SQLITE_ROW],
181a0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
181b0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
181c0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61  the same value a
181d0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  s the [sqlite3_c
181e0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20 66  olumn_count()] f
181f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 33  unction..** {F13
18200 37 37 32 7d 0a 2a 2a 20 41 66 74 65 72 20 5b 73  772}.** After [s
18210 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
18220 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 20 5b  as returned an [
18230 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
18240 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 0a  QLITE_BUSY], or.
18250 2a 2a 20 61 20 5b 53 51 4c 49 54 45 5f 45 52 52  ** a [SQLITE_ERR
18260 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
18270 2c 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c  , or before [sql
18280 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
18290 20 62 65 65 6e 20 0a 2a 2a 20 63 61 6c 6c 65 64   been .** called
182a0 20 6f 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33   on the [sqlite3
182b0 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
182c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20   statement] for 
182d0 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 2c 0a  the first time,.
182e0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
182f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f  returns zero..*/
18300 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
18310 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
18320 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
18330 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
18340 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
18350 79 70 65 73 20 7b 46 31 30 32 36 35 7d 0a 2a 2a  ypes {F10265}.**
18360 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76 65 72  .** {F10266}Ever
18370 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
18380 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
18390 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
183a0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
183b0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
183c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
183d0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
183e0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
183f0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
18400 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
18410 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
18420 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NULL.** </ul> {E
18430 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
18440 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
18450 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
18460 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
18470 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
18480 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
18490 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
184a0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
184b0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
184c0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
184d0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
184e0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
184f0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
18500 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
18510 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
18520 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
18530 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
18540 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  T not.** SQLITE_
18550 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
18560 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
18570 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
18580 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
18590 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
185a0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
185b0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
185c0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
185d0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
185e0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
185f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
18600 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
18610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
18620 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
18630 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
18640 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  lts Values From 
18650 41 20 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d  A Query {F13800}
18660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18670 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
18680 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a  ormation about.*
18690 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  * a single colum
186a0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
186b0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
186c0 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72   query.  In ever
186d0 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69  y.** case the fi
186e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
186f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
18700 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
18710 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65  mt | SQL stateme
18720 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
18730 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28  g.** evaluated (
18740 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
18750 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74  t*] that was ret
18760 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  urned from .** [
18770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18780 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
18790 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e  its variants) an
187a0 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  d.** the second 
187b0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
187c0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
187d0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
187e0 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68  formation .** sh
187f0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
18800 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  .  The left-most
18810 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
18820 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73  esult set.** has
18830 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a   an index of 0..
18840 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
18850 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
18860 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
18870 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
18880 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74  , or if the.** t
18890 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  he column index 
188a0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
188b0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
188c0 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68  ndefined. .** Th
188d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
188e0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
188f0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
18900 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
18910 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18920 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
18930 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
18940 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
18950 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
18960 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
18970 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  e()] has been ca
18980 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ll subsequently.
18990 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
189a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
189b0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
189c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
189d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
189e0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
189f0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
18a00 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
18a10 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
18a20 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
18a30 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
18a40 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
18a50 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
18a60 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
18a70 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
18a80 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
18a90 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
18aa0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
18ab0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
18ac0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
18ad0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
18ae0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
18af0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
18b00 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a  defined.  .**.**
18b10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
18b20 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
18b30 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  ne returns .** [
18b40 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
18b50 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
18b60 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
18b70 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
18b80 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
18b90 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  n.  The returned
18ba0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
18bb0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
18bc0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
18bd0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
18be0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
18bf0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
18c00 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
18c10 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
18c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
18c30 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
18c40 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
18c50 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
18c60 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
18c70 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
18c80 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
18c90 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
18ca0 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
18cb0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18cc0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
18cd0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
18ce0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
18cf0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
18d00 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
18d10 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
18d20 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
18d30 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
18d40 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
18d50 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
18d60 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
18d70 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
18d80 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
18d90 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75  _bytes() .** rou
18da0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
18db0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
18dc0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
18dd0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
18de0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
18df0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
18e00 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
18e10 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
18e20 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
18e30 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
18e40 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
18e50 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
18e60 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
18e70 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
18e80 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
18e90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
18ea0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
18eb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
18ec0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
18ed0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
18ee0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
18ef0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
18f00 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
18f10 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
18f20 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
18f30 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
18f40 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
18f50 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
18f60 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
18f70 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
18f80 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18f90 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
18fa0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
18fb0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
18fc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
18fd0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74  acters..**.** St
18fe0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
18ff0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
19000 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
19010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
19020 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 7a 65 72  6(),.** even zer
19030 6f 2d 6c 65 6e 67 74 68 20 73 74 72 69 6e 67 73  o-length strings
19040 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
19050 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
19060 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
19070 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
19080 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
19090 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
190a0 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69 74  blob is an arbit
190b0 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
190c0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
190d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
190e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
190f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
19100 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
19110 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
19120 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
19130 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
19140 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
19150 36 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  6 instead of UTF
19160 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72  -8.  .** The zer
19170 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
19180 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
19190 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
191a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
191b0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
191c0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
191d0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
191e0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
191f0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
19200 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
19210 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
19220 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
19230 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
19240 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
19250 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
19260 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63  ally to do the c
19270 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74  onversion.** aut
19280 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
19290 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
192a0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
192b0 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a  versions that.**
192c0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
192d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
192e0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
192f0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
19300 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
19310 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
19320 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
19330 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
19340 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
19350 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
19360 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
19370 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
19380 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
19390 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
193a0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
193b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
193c0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
193d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
193e0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
193f0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
19400 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
19410 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
19420 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
19430 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
19440 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
19450 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
19460 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
19470 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
19480 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
19490 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
194a0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
194b0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
194c0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
194d0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
194e0 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49  d> Same as for I
194f0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
19500 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
19510 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
19520 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
19530 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
19540 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
19550 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
19560 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
19570 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
19580 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
19590 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
195a0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
195b0 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
195c0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
195d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
195e0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
195f0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
19600 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
19610 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
19620 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
19630 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
19640 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
19650 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
19660 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
19670 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
19680 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
19690 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
196a0 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
196b0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
196c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
196d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
196e0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
196f0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
19700 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
19710 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
19720 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
19730 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
19740 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
19750 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
19760 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
19770 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
19780 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
19790 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
197a0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
197b0 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
197c0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
197d0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
197e0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
197f0 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74 20  * on equavalent 
19800 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
19810 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
19820 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
19830 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
19840 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
19850 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
19860 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
19870 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
19880 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
19890 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
198a0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
198b0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
198c0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
198d0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
198e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
198f0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
19900 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
19910 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
19920 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
19930 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
19940 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f  ted. .** Type co
19950 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
19960 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
19970 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
19980 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
19990 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
199a0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e   <ul>.** <li><p>
199b0 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
199c0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
199d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
199e0 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20  mn_text() .**   
199f0 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65         or sqlite
19a00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
19a10 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
19a20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
19a30 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20  might.**        
19a40 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
19a50 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
19a60 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  .</p></li>.**.**
19a70 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
19a80 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
19a90 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
19aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
19ab0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
19ac0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
19ad0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
19ae0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
19af0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
19b00 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
19b10 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
19b20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
19b30 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
19b40 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
19b50 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
19b60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
19b70 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
19b80 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
19b90 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
19ba0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
19bb0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
19bc0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  erted.**        
19bd0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c    to UTF-8.</p><
19be0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
19bf0 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
19c00 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
19c10 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
19c20 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
19c30 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
19c40 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
19c50 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
19c60 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
19c70 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
19c80 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
19c90 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
19ca0 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
19cb0 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
19cc0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
19cd0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
19ce0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
19cf0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
19d00 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
19d10 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73  t sometime it is
19d20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
19d30 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
19d40 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
19d50 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
19d60 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ed.  .**.** The 
19d70 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
19d80 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
19d90 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
19da0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
19db0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
19dc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
19dd0 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a  s:.**.**  <ul>.*
19de0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
19df0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
19e00 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
19e10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
19e20 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
19e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
19e40 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
19e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
19e60 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
19e70 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
19e80 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
19e90 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
19ea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
19eb0 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a  /li>.**  </ul>.*
19ec0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
19ed0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
19ee0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
19ef0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  umn_text(), sqli
19f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
19f10 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ),.** or sqlite3
19f20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
19f30 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
19f40 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
19f50 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66  the desired.** f
19f60 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
19f70 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
19f80 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c  n_bytes() or sql
19f90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
19fa0 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64  s16() to.** find
19fb0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
19fc0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
19fd0 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c   mix call to sql
19fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
19ff0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
1a000 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
1a010 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
1a020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
1a030 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e  s16().  And do n
1a040 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20  ot.** mix calls 
1a050 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
1a060 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20  n_text16() with 
1a070 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
1a080 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
1a090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1a0a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
1a0b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
1a0c0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
1a0d0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
1a0e0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
1a0f0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
1a100 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
1a110 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
1a120 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
1a130 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
1a140 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70  .  The memory sp
1a150 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
1a160 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
1a170 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20 61  blobs is freed a
1a180 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
1a190 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
1a1a0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
1a1b0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
1a1c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
1a1d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
1a1e0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
1a1f0 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69  . into .** [sqli
1a200 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
1a210 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  ** If a memory a
1a220 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
1a230 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
1a240 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
1a250 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
1a260 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
1a270 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
1a280 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
1a290 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
1a2a0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
1a2b0 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
1a2c0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
1a2d0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
1a2e0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
1a2f0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1a300 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1a310 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
1a320 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
1a330 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  ]..*/.const void
1a340 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1a350 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
1a360 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
1a370 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
1a380 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
1a390 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
1a3a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1a3b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
1a3c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1a3d0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
1a3e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
1a3f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1a400 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
1a410 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1a420 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
1a430 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
1a440 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1a450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
1a460 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
1a470 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
1a480 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
1a490 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1a4a0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
1a4b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
1a4c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1a4d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
1a4e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1a4f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
1a500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1a510 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
1a520 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
1a530 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
1a540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1a550 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1a560 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
1a570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
1a580 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
1a590 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
1a5a0 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13300}.**.** 
1a5b0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
1a5c0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
1a5d0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
1a5e0 65 74 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74  ete a .** [sqlit
1a5f0 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
1a600 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1a610 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  ]. If the statem
1a620 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75  ent was.** execu
1a630 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ted successfully
1a640 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  , or not execute
1a650 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53  d at all, then S
1a660 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
1a670 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63  rned..** If exec
1a680 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
1a690 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
1a6a0 65 6e 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  en an .** [SQLIT
1a6b0 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
1a6c0 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45  code] or [SQLITE
1a6d0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
1a6e0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1a6f0 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  e].** is returne
1a700 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  d. .**.** This r
1a710 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
1a720 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
1a730 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
1a740 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
1a750 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
1a760 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
1a770 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
1a780 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
1a790 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  ot .** completed
1a7a0 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
1a7b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1a7c0 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
1a7d0 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
1a7e0 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
1a7f0 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20   an interrupt.  
1a800 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  (See [sqlite3_in
1a810 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a  terrupt()].) .**
1a820 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
1a830 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
1a840 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
1a850 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65  actions cancelle
1a860 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  d,  .** dependin
1a870 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
1a880 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20  tances, and the 
1a890 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
1a8a0 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  R | result code]
1a8b0 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
1a8c0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
1a8d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a8e0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
1a8f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1a900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a910 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
1a920 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
1a930 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a  ct {F13330}.**.*
1a940 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
1a950 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
1a960 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
1a970 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t a .** [sqlite3
1a980 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
1a990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
1a9a0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20  object..** back 
1a9b0 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61 6c 20  to it's initial 
1a9c0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
1a9d0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
1a9e0 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  ** Any SQL state
1a9f0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
1aa00 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
1aa10 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
1aa20 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
1aa30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
1aa40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1aa50 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
1aa60 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
1aa70 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
1aa80 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
1aa90 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
1aaa0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
1aab0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
1aac0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1aad0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1aae0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
1aaf0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20  e SQL Functions 
1ab00 7b 46 31 36 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16100}.**.** T
1ab10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
1ab20 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
1ab30 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
1ab40 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
1ab50 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20  egates.** or to 
1ab60 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
1ab70 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e  avior of existin
1ab80 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
1ab90 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
1aba0 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63  The.** differenc
1abb0 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74  e only between t
1abc0 68 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  he two is that t
1abd0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1abe0 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65  ter, the.** name
1abf0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
1ac00 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
1ac10 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
1ac20 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a  ed in UTF-8 for.
1ac30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
1ac40 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
1ac50 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69   UTF-16 for sqli
1ac60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1ac70 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
1ac80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1ac90 74 20 69 73 20 74 68 65 20 5b 73 71 6c 69 74 65  t is the [sqlite
1aca0 33 20 7c 20 64 61 74 61 62 61 73 65 20 68 61 6e  3 | database han
1acb0 64 6c 65 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  dle] that holds 
1acc0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
1acd0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
1ace0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 20   is to be added 
1acf0 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 20 49 66  or redefined. If
1ad00 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f   a single.** pro
1ad10 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
1ad20 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
1ad30 20 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61 6c   handle internal
1ad40 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20  ly, then SQL.** 
1ad50 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
1ad60 72 65 67 61 74 65 73 20 6d 75 73 74 20 62 65 20  regates must be 
1ad70 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
1ad80 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ly to each datab
1ad90 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 77 69  ase.** handle wi
1ada0 74 68 20 77 68 69 63 68 20 74 68 65 79 20 77 69  th which they wi
1adb0 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ll be used..**.*
1adc0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
1add0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
1ade0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
1adf0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
1ae00 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66  ated.** or redef
1ae10 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e  ined..** The len
1ae20 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
1ae30 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
1ae40 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
1ae50 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65  ve of the .** ze
1ae60 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
1ae70 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
1ae80 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
1ae90 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
1aea0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
1aeb0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
1aec0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
1aed0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
1aee0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
1aef0 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45  ult in an SQLITE
1af00 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a  _ERROR error..**
1af10 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61  .** The third pa
1af20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
1af30 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
1af40 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
1af50 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
1af60 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
1af70 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
1af80 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
1af90 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
1afa0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
1afb0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
1afc0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
1afd0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
1afe0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1aff0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
1b000 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20  cifies what .** 
1b010 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
1b020 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
1b030 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
1b040 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
1b050 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
1b060 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
1b070 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1b080 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
1b090 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
1b0a0 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
1b0b0 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
1b0c0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
1b0d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
1b0e0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
1b0f0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
1b100 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
1b110 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
1b120 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
1b130 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1b140 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
1b150 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1b160 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
1b170 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
1b180 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
1b190 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
1b1a0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
1b1b0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
1b1c0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
1b1d0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
1b1e0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
1b1f0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
1b200 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
1b210 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
1b220 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
1b230 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
1b240 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
1b250 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
1b260 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
1b270 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
1b280 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
1b290 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  at.** text encod
1b2a0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1b2b0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
1b2c0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a  ument should be.
1b2d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  ** [SQLITE_ANY].
1b2e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
1b2f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
1b300 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
1b310 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
1b320 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
1b330 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  e function can g
1b340 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
1b350 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
1b360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  .** [sqlite3_use
1b370 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
1b380 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
1b390 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
1b3a0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
1b3b0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
1b3c0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
1b3d0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
1b3e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
1b3f0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
1b400 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f  QL.** function o
1b410 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  r aggregate. A s
1b420 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
1b430 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
1b440 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b450 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61  .** the xFunc ca
1b460 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
1b470 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
1b480 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
1b490 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  he xStep.** and 
1b4a0 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  xFinal parameter
1b4b0 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
1b4c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
1b4d0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
1b4e0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53  ntation.** of xS
1b4f0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  tep and xFinal a
1b500 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
1b510 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
1b520 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
1b530 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c  .** existing SQL
1b540 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
1b550 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
1b560 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
1b570 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
1b580 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  back..**.** It i
1b590 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
1b5a0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
1b5b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
1b5c0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
1b5d0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
1b5e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
1b5f0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
1b600 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
1b610 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
1b620 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 72 66  r differing perf
1b630 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
1b640 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
1b650 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
1b660 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73  plementation mos
1b670 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
1b680 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
1b690 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
1b6a0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  nction is used..
1b6b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1b6c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
1b6d0 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20 63    sqlite3 *,.  c
1b6e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
1b6f0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
1b700 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
1b710 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20  tRep,.  void*,. 
1b720 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
1b730 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b740 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
1b750 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
1b760 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
1b770 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
1b780 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
1b790 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
1b7a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
1b7b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1b7c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
1b7d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1b7e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
1b7f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
1b800 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
1b810 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a  xtRep,.  void*,.
1b820 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
1b830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b840 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
1b850 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
1b860 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
1b870 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
1b880 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
1b890 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
1b8a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
1b8b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1b8c0 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
1b8d0 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a  ngs {F10267}.**.
1b8e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
1b8f0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
1b900 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
1b910 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
1b920 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
1b930 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
1b940 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
1b950 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
1b960 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1b970 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
1b980 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
1b990 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
1b9a0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
1b9b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
1b9c0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
1b9d0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
1b9e0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
1b9f0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
1ba00 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
1ba10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1ba20 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
1ba30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ba40 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
1ba50 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
1ba60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
1ba70 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
1ba80 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74  API3REF: Obsolet
1ba90 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  e Functions.**.*
1baa0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
1bab0 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62  s are all now ob
1bac0 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65  solete.  In orde
1bad0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
1bae0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1baf0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
1bb00 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e  der code, we con
1bb10 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74  tinue to support
1bb20 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
1bb30 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ons.  However, n
1bb40 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70  ew development p
1bb50 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61  rojects should a
1bb60 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
1bb70 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
1bb80 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
1bb90 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
1bba0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
1bbb0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
1bbc0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
1bbd0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
1bbe0 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
1bbf0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
1bc00 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
1bc10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
1bc20 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
1bc30 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
1bc40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
1bc50 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
1bc60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
1bc70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
1bc80 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
1bc90 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
1bca0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
1bcb0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
1bcc0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1bcd0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
1bce0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
1bcf0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
1bd00 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
1bd10 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
1bd20 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
1bd30 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
1bd40 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31  meter Values {F1
1bd50 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  5100}.**.** The 
1bd60 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
1bd70 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
1bd80 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
1bd90 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
1bda0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
1bdb0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
1bdc0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
1bdd0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
1bde0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
1bdf0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
1be00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
1be10 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
1be20 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
1be30 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
1be40 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
1be50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
1be60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
1be70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
1be80 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
1be90 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
1bea0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
1beb0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
1bec0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
1bed0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
1bee0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1bef0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
1bf00 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1bf10 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  nters to.** [sql
1bf20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1bf30 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
1bf40 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
1bf50 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
1bf60 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
1bf70 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
1bf80 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
1bf90 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
1bfa0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
1bfb0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
1bfc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1bfd0 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
1bfe0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
1bff0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
1c000 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b  responding .** [
1c010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
1c020 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  lob | sqlite3_co
1c030 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d  lumn_* routines]
1c040 20 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a   except that .**
1c050 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1c060 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 73  take a single [s
1c070 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
1c080 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a  ointer instead.*
1c090 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
1c0a0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
1c0b0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
1c0c0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
1c0d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1c0e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
1c0f0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
1c100 73 20 61 20 55 54 46 31 36 20 73 74 72 69 6e 67  s a UTF16 string
1c110 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
1c120 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
1c130 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
1c140 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
1c150 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
1c160 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1c170 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
1c180 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
1c190 74 72 61 63 74 20 55 54 46 31 36 20 73 74 72 69  tract UTF16 stri
1c1a0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
1c1b0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
1c1c0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
1c1d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1c1e0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
1c1f0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
1c200 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
1c210 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
1c220 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
1c230 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
1c240 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
1c250 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
1c260 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
1c270 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
1c280 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
1c290 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
1c2a0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
1c2b0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
1c2c0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
1c2d0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
1c2e0 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65 20 76  * words if the v
1c2f0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
1c300 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
1c310 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
1c320 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
1c330 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65  n is done.  Othe
1c340 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
1c350 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ion occurs.  The
1c360 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54   .** [SQLITE_INT
1c370 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
1c380 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
1c390 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  n is returned..*
1c3a0 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
1c3b0 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
1c3c0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
1c3d0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
1c3e0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74  r that.** is ret
1c3f0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
1c400 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
1c410 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
1c420 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
1c430 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1c440 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
1c450 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
1c460 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
1c470 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
1c480 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
1c490 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1c4a0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
1c4b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
1c4c0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
1c4d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
1c4e0 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73  )].  .**.** Thes
1c4f0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
1c500 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
1c510 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
1c520 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
1c530 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
1c540 69 65 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ied the sqlite3_
1c550 76 61 6c 75 65 2a 20 70 61 72 61 6d 65 74 65 72  value* parameter
1c560 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20 74 68 65  s..** Or, if the
1c570 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20   sqlite3_value* 
1c580 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65 73 20 66  argument comes f
1c590 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1c5a0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1c5b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2c 20 74  .** interface, t
1c5c0 68 65 6e 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hen these routin
1c5d0 65 73 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  es should be cal
1c5e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
1c5f0 65 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 74  e thread.** that
1c600 20 72 61 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6f   ran [sqlite3_co
1c610 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  lumn_value()]..*
1c620 2a 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  *.*/.const void 
1c630 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
1c640 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
1c650 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1c660 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
1c670 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
1c680 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
1c690 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
1c6a0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
1c6b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
1c6c0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
1c6d0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
1c6e0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
1c6f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
1c700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1c710 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
1c720 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
1c730 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
1c740 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
1c750 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
1c760 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
1c770 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
1c780 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
1c790 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
1c7a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
1c7b0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
1c7c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
1c7d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1c7e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
1c7f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
1c800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
1c810 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
1c820 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
1c830 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
1c840 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
1c850 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
1c860 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
1c870 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
1c880 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46  ction Context {F
1c890 31 36 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16210}.**.** The
1c8a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c8b0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
1c8c0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
1c8d0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
1c8e0 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
1c8f0 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
1c900 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 20  ng their state. 
1c910 20 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68   .** {F16211} Th
1c920 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
1c930 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
1c940 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75  te_context() rou
1c950 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63 61  tine is.** is ca
1c960 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69  lled for a parti
1c970 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
1c980 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
1c990 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
1c9a0 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74  ry.** zeros that
1c9b0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
1c9c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1c9d0 6f 20 69 74 2e 0a 2a 2a 20 7b 46 31 36 32 31 32  o it..** {F16212
1c9e0 7d 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20  } On second and 
1c9f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1ca00 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
1ca10 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 0a  egate_context().
1ca20 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
1ca30 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
1ca40 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65 20 73 61  on index, the sa
1ca50 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
1ca60 75 72 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  urned. {END}.** 
1ca70 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
1ca80 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67  on.** of the agg
1ca90 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74  regate can use t
1caa0 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
1cab0 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
1cac0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   data..**.** {F1
1cad0 36 32 31 33 7d 20 53 51 4c 69 74 65 20 61 75 74  6213} SQLite aut
1cae0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
1caf0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
1cb00 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
1cb10 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
1cb20 79 20 63 6f 6e 63 6c 75 64 65 73 2e 20 7b 45 4e  y concludes. {EN
1cb30 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  D}.**.** The fir
1cb40 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  st parameter sho
1cb50 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66  uld be a copy of
1cb60 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
1cb70 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
1cb80 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
1cb90 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
1cba0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1cbb0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1cbc0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
1cbd0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
1cbe0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
1cbf0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
1cc00 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
1cc10 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
1cc20 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
1cc30 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
1cc40 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
1cc50 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
1cc60 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
1cc70 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
1cc80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1cc90 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
1cca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ccb0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
1ccc0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30  unctions {F16240
1ccd0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 31 7d  }.**.** {F16241}
1cce0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65   The sqlite3_use
1ccf0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
1cd00 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
1cd10 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
1cd20 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
1cd30 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
1cd40 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
1cd50 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
1cd60 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  he the [sqlite3_
1cd70 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
1cd80 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
1cd90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1cda0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
1cdb0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
1cdc0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
1cdd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1cde0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
1cdf0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 55 31   {END}.**.** {U1
1ce00 36 32 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69  6243} This routi
1ce10 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
1ce20 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
1ce30 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
1ce40 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1ce50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
1ce60 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
1ce70 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1ce80 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
1ce90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
1cea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1ceb0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
1cec0 79 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a  y Data {F16270}.
1ced0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
1cee0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
1cef0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
1cf00 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
1cf10 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
1cf20 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20  ciate meta-data 
1cf30 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
1cf40 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
1cf50 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
1cf60 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
1cf70 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1cf80 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
1cf90 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
1cfa0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
1cfb0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
1cfc0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
1cfd0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61  sociated meta-da
1cfe0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
1cff0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
1d000 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
1d010 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
1d020 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
1d030 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
1d040 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
1d050 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
1d060 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
1d070 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
1d080 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
1d090 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61  eta-data associa
1d0a0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
1d0b0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
1d0c0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
1d0d0 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
1d0e0 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
1d0f0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
1d100 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
1d110 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
1d120 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1d130 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
1d140 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
1d150 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
1d160 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
1d170 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
1d180 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
1d190 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
1d1a0 2a 2a 20 7b 46 31 36 32 37 31 7d 0a 2a 2a 20 54  ** {F16271}.** T
1d1b0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
1d1c0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
1d1d0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
1d1e0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
1d1f0 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
1d200 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1d210 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1d220 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
1d230 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
1d240 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
1d250 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1d260 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
1d270 20 7b 46 31 36 32 37 32 7d 20 49 66 20 6e 6f 20   {F16272} If no 
1d280 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65  meta-data has be
1d290 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65 74  en ever been set
1d2a0 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20   for the Nth.** 
1d2b0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
1d2c0 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
1d2d0 74 68 65 20 63 6f 6f 72 65 73 70 6f 6e 64 69 6e  the coorespondin
1d2e0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
1d2f0 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e  eter.** has chan
1d300 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
1d310 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
1d320 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
1d330 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 72  t_auxdata().** r
1d340 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1d350 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  inter..**.** {F1
1d360 36 32 37 35 7d 20 54 68 65 20 73 71 6c 69 74 65  6275} The sqlite
1d370 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
1d380 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
1d390 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a  the meta-data.**
1d3a0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
1d3b0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1d3c0 20 61 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74   as the meta-dat
1d3d0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
1d3e0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
1d3f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
1d400 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
1d410 7b 45 4e 44 7d 20 53 75 62 73 65 71 75 65 6e 74  {END} Subsequent
1d420 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
1d430 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1d440 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
1d450 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
1d460 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
1d470 20 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20   destroyed. .** 
1d480 7b 46 31 36 32 37 37 7d 20 49 66 20 69 74 20 69  {F16277} If it i
1d490 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
1d4a0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
1d4b0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a  he destructor .*
1d4c0 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
1d4d0 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
1d4e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d4f0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
1d500 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61  n.** the meta-da
1d510 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
1d520 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
1d530 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
1d540 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
1d550 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1d560 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
1d570 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
1d580 73 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  st. {END}.**.** 
1d590 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
1d5a0 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 72  a-data is preser
1d5b0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
1d5c0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
1d5d0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
1d5e0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
1d5f0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
1d600 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
1d610 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
1d620 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
1d630 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
1d640 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
1d650 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
1d660 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
1d670 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
1d680 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
1d690 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
1d6a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
1d6b0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
1d6c0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
1d6d0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
1d6e0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
1d6f0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
1d700 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
1d710 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
1d720 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
1d730 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
1d740 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
1d750 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38 30  Behavior {F10280
1d760 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  }.**.** These ar
1d770 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1d780 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
1d790 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
1d7a0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
1d7b0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
1d7c0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
1d7d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
1d7e0 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20  lob()].  If the 
1d7f0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
1d800 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
1d810 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
1d820 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
1d830 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
1d840 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
1d850 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
1d860 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
1d870 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
1d880 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c  ed.  The .** SQL
1d890 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
1d8a0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
1d8b0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
1d8c0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
1d8d0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
1d8e0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
1d8f0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
1d900 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1d910 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
1d920 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
1d930 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
1d940 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
1d950 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
1d960 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
1d970 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
1d980 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
1d990 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
1d9a0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
1d9b0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
1d9c0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
1d9d0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
1d9e0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
1d9f0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
1da00 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
1da10 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
1da20 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
1da30 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
1da40 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
1da50 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
1da60 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
1da70 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34  L Function {F164
1da80 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
1da90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1daa0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
1dab0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
1dac0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
1dad0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
1dae0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
1daf0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
1db00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1db10 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1db20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1db30 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
1db40 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
1db50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
1db60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
1db70 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
1db80 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  e the .** [sqlit
1db90 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
1dba0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66  qlite3_bind_*] f
1dbb0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1dbc0 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69  ns used.** to bi
1dbd0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
1dbe0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
1dbf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1dc00 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
1dc10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1dc20 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
1dc30 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75  ite3_bind_* docu
1dc40 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a  mentation] for.*
1dc50 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
1dc60 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1dc70 7b 46 31 36 34 30 32 7d 20 54 68 65 20 73 71 6c  {F16402} The sql
1dc80 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
1dc90 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
1dca0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
1dcb0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
1dcc0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
1dcd0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
1dce0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
1dcf0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
1dd00 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
1dd10 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
1dd20 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
1dd30 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
1dd40 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
1dd50 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 7b 46 31 36  ameter. .** {F16
1dd60 34 30 33 7d 20 54 68 65 20 73 71 6c 69 74 65 33  403} The sqlite3
1dd70 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
1dd80 28 29 20 69 6e 65 72 66 61 63 65 73 20 73 65 74  () inerfaces set
1dd90 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
1dda0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1ddb0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
1ddc0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
1ddd0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
1dde0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
1ddf0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1de00 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1de10 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
1de20 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1de30 2a 2a 20 7b 46 31 36 34 30 37 7d 20 54 68 65 20  ** {F16407} The 
1de40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
1de50 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
1de60 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
1de70 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
1de80 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
1de90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
1dea0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
1deb0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
1dec0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
1ded0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  rgument..**.** {
1dee0 46 31 36 34 30 39 7d 20 54 68 65 20 73 71 6c 69  F16409} The sqli
1def0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1df00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1df10 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
1df20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
1df30 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
1df40 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
1df50 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
1df60 70 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 34 31  ption..** {F1641
1df70 31 7d 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  1} SQLite uses t
1df80 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
1df90 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
1dfa0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
1dfb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
1dfc0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
1dfd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
1dfe0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
1dff0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
1e000 73 73 61 67 65 2e 20 7b 46 31 36 34 31 32 7d 20  ssage. {F16412} 
1e010 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
1e020 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
1e030 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
1e040 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
1e050 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
1e060 38 2e 20 20 7b 46 31 36 34 31 33 7d 20 53 51 4c  8.  {F16413} SQL
1e070 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
1e080 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
1e090 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
1e0a0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
1e0b0 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  F16 in native.**
1e0c0 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 7b 46   byte order.  {F
1e0d0 31 36 34 31 34 7d 20 49 66 20 74 68 65 20 74 68  16414} If the th
1e0e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
1e0f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1e100 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
1e110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1e120 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
1e130 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
1e140 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
1e150 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
1e160 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
1e170 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1e180 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 7b 46  character..** {F
1e190 31 36 34 31 35 7d 20 49 66 20 74 68 65 20 74 68  16415} If the th
1e1a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
1e1b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1e1c0 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
1e1d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1e1e0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
1e1f0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
1e200 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
1e210 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
1e220 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
1e230 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
1e240 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
1e250 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 7b 46 31   message..** {F1
1e260 36 34 31 37 7d 20 54 68 65 20 73 71 6c 69 74 65  6417} The sqlite
1e270 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
1e280 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
1e290 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
1e2a0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
1e2b0 20 63 6f 70 79 20 70 72 69 76 61 74 65 20 63 6f   copy private co
1e2c0 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
1e2d0 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
1e2e0 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
1e2f0 72 6e 2e 20 20 7b 45 4e 44 7d 20 48 65 6e 63 65  rn.  {END} Hence
1e300 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
1e310 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
1e320 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
1e330 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
1e340 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
1e350 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 0a 2a  thout harm..**.*
1e360 2a 20 7b 46 31 36 34 32 31 7d 20 54 68 65 20 73  * {F16421} The s
1e370 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
1e380 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
1e390 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 0a 2a   causes SQLite.*
1e3a0 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  * to throw an er
1e3b0 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
1e3c0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
1e3d0 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a  BLOB is to long.
1e3e0 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ** to represent.
1e3f0 20 20 7b 46 31 36 34 32 32 7d 20 54 68 65 20 73    {F16422} The s
1e400 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
1e410 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mem() interface.
1e420 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ** causes SQLite
1e430 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
1e440 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e  eption indicatin
1e450 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a 20  g that the a.** 
1e460 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e470 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
1e480 7b 46 31 36 34 33 31 7d 20 54 68 65 20 73 71 6c  {F16431} The sql
1e490 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
1e4a0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
1e4b0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1e4c0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
1e4d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1e4e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
1e4f0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
1e500 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
1e510 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
1e520 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
1e530 7b 46 31 36 34 33 32 7d 20 54 68 65 20 73 71 6c  {F16432} The sql
1e540 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
1e550 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
1e560 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
1e570 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
1e580 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1e590 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
1e5a0 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
1e5b0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
1e5c0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
1e5d0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
1e5e0 2a 0a 2a 2a 20 7b 46 31 36 34 33 37 7d 20 54 68  *.** {F16437} Th
1e5f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
1e600 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
1e610 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
1e620 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
1e630 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
1e640 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
1e650 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
1e660 20 7b 46 31 36 34 34 31 7d 20 54 68 65 20 73 71   {F16441} The sq
1e670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1e680 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
1e690 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a  ult_text16(), .*
1e6a0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
1e6b0 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
1e6c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1e6d0 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
1e6e0 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
1e6f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1e700 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e710 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
1e720 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
1e730 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
1e740 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
1e750 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
1e760 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1e770 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
1e780 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
1e790 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
1e7a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1e7b0 2a 20 7b 46 31 36 34 34 32 7d 20 53 51 4c 69 74  * {F16442} SQLit
1e7c0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
1e7d0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
1e7e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
1e7f0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
1e800 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
1e810 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1e820 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
1e830 2a 20 7b 46 31 36 34 34 34 7d 20 49 66 20 74 68  * {F16444} If th
1e840 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1e850 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
1e860 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
1e870 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
1e880 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
1e890 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
1e8a0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
1e8b0 64 20 70 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20  d parameter .** 
1e8c0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
1e8d0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
1e8e0 2e 0a 2a 2a 20 7b 46 31 36 34 34 37 7d 20 49 66  ..** {F16447} If
1e8f0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1e900 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1e910 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
1e920 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
1e930 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1e940 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
1e950 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
1e960 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
1e970 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
1e980 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
1e990 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
1e9a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
1e9b0 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
1e9c0 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31  n result..** {F1
1e9d0 36 34 35 31 7d 20 49 66 20 74 68 65 20 34 74 68  6451} If the 4th
1e9e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e9f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
1ea00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
1ea10 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
1ea20 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
1ea30 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1ea40 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
1ea50 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
1ea60 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
1ea70 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
1ea80 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
1ea90 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
1eaa0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
1eab0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
1eac0 20 7b 46 31 36 34 35 33 7d 20 49 66 20 74 68 65   {F16453} If the
1ead0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
1eae0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
1eaf0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
1eb00 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
1eb10 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
1eb20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
1eb30 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
1eb40 54 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53  TATIC, then.** S
1eb50 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
1eb60 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  at the text or b
1eb70 6c 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f  lob result is co
1eb80 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
1eb90 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70  .** does not cop
1eba0 79 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63  y the space or c
1ebb0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
1ebc0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
1ebd0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
1ebe0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 7b  hat result..** {
1ebf0 46 31 36 34 35 34 7d 20 49 66 20 74 68 65 20 34  F16454} If the 4
1ec00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1ec10 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
1ec20 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
1ec30 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
1ec40 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
1ec50 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
1ec60 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
1ec70 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
1ec80 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
1ec90 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
1eca0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
1ecb0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
1ecc0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1ecd0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
1ece0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  eturns..**.** {F
1ecf0 31 36 34 36 31 7d 20 54 68 65 20 73 71 6c 69 74  16461} The sqlit
1ed00 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1ed10 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
1ed20 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
1ed30 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1ed40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
1ed50 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
1ed60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
1ed70 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 73 70  ue].** object sp
1ed80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
1ed90 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 7b  nd parameter.  {
1eda0 46 31 36 34 36 33 7d 20 54 68 65 0a 2a 2a 20 73  F16463} The.** s
1edb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
1edc0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
1edd0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
1ede0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
1edf0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b  ue].** so that [
1ee00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
1ee10 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
1ee20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
1ee30 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
1ee40 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
1ee50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1ee60 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
1ee70 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 0a  ithout harm..**.
1ee80 2a 2a 20 7b 55 31 36 34 39 31 7d 20 54 68 65 73  ** {U16491} Thes
1ee90 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
1eea0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
1eeb0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
1eec0 74 68 72 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20  thread .** than 
1eed0 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
1eee0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
1eef0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
1ef00 69 6f 6e 20 74 68 61 74 20 72 65 63 69 65 76 65  ion that recieve
1ef10 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
1ef20 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
1ef30 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
1ef40 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
1ef50 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
1ef60 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
1ef70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1ef80 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
1ef90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1efa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1efb0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
1efc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
1efd0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
1efe0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1eff0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1f000 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
1f010 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1f020 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
1f030 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1f040 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1f050 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1f060 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
1f070 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
1f080 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
1f090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1f0a0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
1f0b0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
1f0c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1f0d0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
1f0e0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
1f0f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1f100 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
1f110 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
1f120 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
1f130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
1f140 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
1f150 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
1f160 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
1f170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1f180 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
1f190 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1f1a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1f1b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
1f1c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
1f1d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1f1e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1f1f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1f200 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
1f210 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1f220 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1f230 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
1f240 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1f250 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
1f260 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1f270 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1f280 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
1f290 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
1f2a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
1f2b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1f2c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
1f2d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
1f2e0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
1f2f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1f300 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1f310 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
1f320 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
1f330 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30  equences {F16600
1f340 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 31 7d  }.**.** {F16601}
1f350 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
1f360 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
1f370 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
1f380 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
1f390 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d  he.** [sqlite3*]
1f3a0 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65   handle specifie
1f3b0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
1f3c0 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20  rgument. .**.** 
1f3d0 7b 46 31 36 36 30 32 7d 0a 2a 2a 20 54 68 65 20  {F16602}.** The 
1f3e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
1f3f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1f400 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
1f410 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
1f420 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
1f430 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1f440 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1f450 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1f460 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
1f470 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
1f480 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1f490 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 7b  collation16(). {
1f4a0 46 31 36 36 30 33 7d 20 49 6e 20 61 6c 6c 20 63  F16603} In all c
1f4b0 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
1f4c0 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
1f4d0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
1f4e0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
1f4f0 2a 20 7b 46 31 36 36 30 34 7d 0a 2a 2a 20 54 68  * {F16604}.** Th
1f500 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1f510 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
1f520 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
1f530 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
1f540 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
1f550 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
1f560 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
1f570 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
1f580 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
1f590 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
1f5a0 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
1f5b0 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
1f5c0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
1f5d0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
1f5e0 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
1f5f0 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
1f600 70 65 63 74 69 76 65 6c 79 2e 20 7b 46 31 36 36  pectively. {F166
1f610 30 35 7d 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  05} The.** third
1f620 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
1f630 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
1f640 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74  UTF16_ALIGNED] t
1f650 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a  o indicate that.
1f660 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
1f670 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
1f680 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
1f690 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
1f6a0 2a 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68  * of UTF16 in th
1f6b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1f6c0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
1f6d0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
1f6e0 7b 46 31 36 36 30 37 7d 0a 2a 2a 20 41 20 70 6f  {F16607}.** A po
1f6f0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
1f700 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
1f710 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
1f720 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
1f730 2a 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 36  * argument. {F16
1f740 36 30 39 7d 20 49 66 20 69 74 20 69 73 20 4e 55  609} If it is NU
1f750 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
1f760 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
1f770 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
1f780 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
1f790 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
1f7a0 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
1f7b0 65 29 2e 0a 2a 2a 20 7b 46 31 36 36 31 31 7d 20  e)..** {F16611} 
1f7c0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
1f7d0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70  plication.** sup
1f7e0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
1f7f0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
1f800 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
1f810 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73  f the void* pass
1f820 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75  ed as.** the fou
1f830 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1f840 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1f850 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a  ollation() or.**
1f860 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1f870 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73  collation16() as
1f880 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
1f890 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  eter..**.** {F16
1f8a0 36 31 32 7d 0a 2a 2a 20 54 68 65 20 72 65 6d 61  612}.** The rema
1f8b0 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
1f8c0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1f8d0 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
1f8e0 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
1f8f0 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
1f900 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 5b 6c  resented by a [l
1f910 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 70 61 69  ength, data] pai
1f920 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
1f930 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
1f940 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
1f950 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
1f960 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
1f970 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1f980 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
1f990 65 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20  ered. {END} The 
1f9a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
1f9b0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
1f9c0 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
1f9d0 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
1f9e0 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
1f9f0 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73  e if.** the firs
1fa00 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
1fa10 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
1fa20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1fa30 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73   the second.** s
1fa40 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
1fa50 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
1fa60 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 0a  .**.** {F16615}.
1fa70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
1fa80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1fa90 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
1faa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1fab0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78  ollation().** ex
1fac0 63 61 70 74 20 74 68 61 74 20 69 74 20 74 61 6b  capt that it tak
1fad0 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75  es an extra argu
1fae0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
1faf0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a  destructor for.*
1fb00 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e  * the collation.
1fb10 20 20 7b 46 31 36 36 31 37 7d 20 54 68 65 20 64    {F16617} The d
1fb20 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
1fb30 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
1fb40 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
1fb50 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
1fb60 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
1fb70 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1fb80 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
1fb90 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the sqli
1fba0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1fbb0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 7b 46  tion_v2()..** {F
1fbc0 31 36 36 31 38 7d 20 20 43 6f 6c 6c 61 74 69 6f  16618}  Collatio
1fbd0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
1fbe0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72   when.** they ar
1fbf0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
1fc00 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
1fc10 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
1fc20 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a  ation functions.
1fc30 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ** or when the [
1fc40 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
1fc50 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f  se handle is clo
1fc60 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
1fc70 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a  e3_close()]..*/.
1fc80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
1fc90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
1fca0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
1fcb0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
1fcc0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
1fcd0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
1fce0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
1fcf0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1fd00 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1fd10 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
1fd20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1fd30 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
1fd40 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
1fd50 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
1fd60 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
1fd70 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
1fd80 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
1fd90 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
1fda0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
1fdb0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
1fdc0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
1fdd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1fde0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
1fdf0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
1fe00 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
1fe10 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
1fe20 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
1fe30 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
1fe40 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
1fe50 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
1fe60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fe70 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
1fe80 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  ed Callbacks {F1
1fe90 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  6700}.**.** {F16
1fea0 37 30 31 7d 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  701}.** To avoid
1feb0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
1fec0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
1fed0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
1fee0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
1fef0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
1ff00 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
1ff10 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
1ff20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
1ff30 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1ff40 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c  handle to be cal
1ff50 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
1ff60 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
1ff70 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a  ion sequence is.
1ff80 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ** required..**.
1ff90 2a 2a 20 7b 46 31 36 37 30 32 7d 0a 2a 2a 20 49  ** {F16702}.** I
1ffa0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
1ffb0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
1ffc0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
1ffd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
1ffe0 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
1fff0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
20000 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
20010 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
20020 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
20030 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
20040 55 54 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20  UTF-8. {F16703} 
20050 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
20060 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
20070 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d  is used, the nam
20080 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  es.** are passed
20090 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
200a0 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
200b0 65 20 6f 72 64 65 72 2e 20 7b 46 31 36 37 30 34  e order. {F16704
200c0 7d 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  } A call to eith
200d0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
200e0 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73  eplaces any exis
200f0 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  ting callback..*
20100 2a 0a 2a 2a 20 7b 46 31 36 37 30 35 7d 20 57 68  *.** {F16705} Wh
20110 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
20120 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
20130 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
20140 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
20150 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
20160 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
20170 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
20180 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
20190 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
201a0 6e 65 65 64 65 64 31 36 28 29 2e 20 7b 46 31 36  needed16(). {F16
201b0 37 30 36 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  706} The second 
201c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
201d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
201e0 6c 65 2e 20 20 7b 46 31 36 37 30 37 7d 20 54 68  le.  {F16707} Th
201f0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
20200 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
20210 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
20220 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
20230 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
20240 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
20250 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72  he most.** desir
20260 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
20270 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
20280 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
20290 75 69 72 65 64 2e 0a 2a 2a 20 7b 46 31 36 37 30  uired..** {F1670
202a0 38 7d 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  8} The fourth pa
202b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
202c0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
202d0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
202e0 20 73 65 71 75 65 6e 63 65 2e 20 7b 45 4e 44 7d   sequence. {END}
202f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
20300 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
20310 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
20320 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
20330 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
20340 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
20350 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
20360 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
20370 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
20380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
20390 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
203a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
203b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
203c0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
203d0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
203e0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
203f0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
20400 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
20410 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
20420 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
20430 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
20440 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
20450 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
20460 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
20470 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
20480 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
20490 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
204a0 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
204b0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
204c0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
204d0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
204e0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
204f0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
20500 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
20510 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
20520 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
20530 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
20540 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
20550 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
20560 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
20570 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
20580 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
20590 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
205a0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
205b0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
205c0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
205d0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
205e0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
205f0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
20600 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
20610 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
20620 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
20630 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
20640 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
20650 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
20660 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
20670 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
20680 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
20690 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
206a0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
206b0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
206c0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
206d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
206e0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
206f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
20700 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
20710 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
20720 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
20730 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
20740 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
20750 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
20760 20 43 41 50 49 33 52 45 46 3a 20 20 53 75 73 70   CAPI3REF:  Susp
20770 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
20780 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b  r A Short Time {
20790 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F10530}.**.** {F
207a0 31 30 35 33 31 7d 20 54 68 65 20 73 71 6c 69 74  10531} The sqlit
207b0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
207c0 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68  ion.** causes th
207d0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
207e0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
207f0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
20800 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
20810 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
20820 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
20830 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
20840 20 7b 46 31 30 35 33 32 7d 20 49 66 20 74 68 65   {F10532} If the
20850 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20860 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
20870 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
20880 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69  s with .** milli
20890 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
208a0 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
208b0 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
208c0 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20  unded up to .** 
208d0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
208e0 6e 64 2e 20 7b 46 31 30 35 33 33 7d 20 54 68 65  nd. {F10533} The
208f0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
20900 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
20910 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65   actually .** re
20920 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
20930 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20940 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
20950 2a 0a 2a 2a 20 7b 46 31 30 35 33 34 7d 20 53 51  *.** {F10534} SQ
20960 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
20970 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
20980 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
20990 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
209a0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
209b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
209c0 6a 65 63 74 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69  ject. {END}.*/.i
209d0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
209e0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
209f0 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66  PI3REF:  Name Of
20a00 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
20a10 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
20a20 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a  les {F10310}.**.
20a30 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
20a40 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
20a50 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
20a60 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
20a70 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
20a80 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20  a folder (a.ka. 
20a90 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
20aa0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
20ab0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
20ac0 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
20ad0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
20ae0 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
20af0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
20b00 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
20b10 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f  , then SQLite do
20b20 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  es a search for 
20b30 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  an appropriate t
20b40 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65  emporary.** file
20b50 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
20b60 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
20b70 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20   to modify this 
20b80 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20  variable once a 
20b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20ba0 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  ion.** has been 
20bb0 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69  opened.  It is i
20bc0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
20bd0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
20be0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
20bf0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
20c00 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
20c10 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
20c20 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
20c30 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
20c40 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69  n call and remai
20c50 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72  n unchanged ther
20c60 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  eafter..*/.SQLIT
20c70 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
20c80 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
20c90 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
20ca0 50 49 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f  PI3REF:  Test To
20cb0 20 53 65 65 20 49 66 20 54 68 65 20 44 61 74 61   See If The Data
20cc0 62 61 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d  base Is In Auto-
20cd0 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32  Commit Mode {F12
20ce0 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  930}.**.** {F129
20cf0 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  31} The sqlite3_
20d00 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
20d10 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
20d20 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
20d30 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
20d40 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
20d50 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
20d60 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
20d70 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
20d80 70 65 63 74 69 76 65 6c 79 2e 20 7b 46 31 32 39  pectively. {F129
20d90 33 32 7d 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20  32}  Autocommit 
20da0 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79  mode is on.** by
20db0 20 64 65 66 61 75 6c 74 2e 20 20 7b 46 31 32 39   default.  {F129
20dc0 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  33} Autocommit m
20dd0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
20de0 62 79 20 61 20 42 45 47 49 4e 20 73 74 61 74 65  by a BEGIN state
20df0 6d 65 6e 74 2e 0a 2a 2a 20 7b 46 31 32 39 33 34  ment..** {F12934
20e00 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
20e10 65 20 69 73 20 72 65 65 6e 61 62 6c 65 64 20 62  e is reenabled b
20e20 79 20 61 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f  y a COMMIT or RO
20e30 4c 4c 42 41 43 4b 2e 20 7b 45 4e 44 7d 0a 2a 2a  LLBACK. {END}.**
20e40 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
20e50 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
20e60 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
20e70 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
20e80 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
20e90 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72  transactions (er
20ea0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
20eb0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
20ec0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a  QLITE_IOERR], .*
20ed0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
20ee0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
20ef0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
20f00 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
20f10 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
20f20 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
20f30 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
20f40 6c 6c 79 2e 20 20 7b 46 31 32 39 33 35 7d 20 54  lly.  {F12935} T
20f50 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
20f60 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51  * find out if SQ
20f70 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
20f80 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
20f90 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
20fa0 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
20fb0 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
20fc0 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
20fd0 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49  **.** {U12936} I
20fe0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
20ff0 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
21000 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
21010 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
21020 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
21030 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
21040 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
21050 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
21060 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
21070 64 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20  d. {END}.*/.int 
21080 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
21090 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
210a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
210b0 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61 74  F:  Find The Dat
210c0 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
210d0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
210e0 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a  ment {F13120}.**
210f0 0a 2a 2a 20 7b 46 31 33 31 32 31 7d 20 54 68 65  .** {F13121} The
21100 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
21110 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  le interface.** 
21120 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73 71 6c  returns the [sql
21130 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20  ite3*] database 
21140 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20  handle to which 
21150 61 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  a.** [sqlite3_st
21160 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
21170 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
21180 2e 0a 2a 2a 20 7b 46 31 33 31 32 32 7d 20 74 68  ..** {F13122} th
21190 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
211a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
211b0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a  lite3_db_handle.
211c0 2a 2a 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  ** is the same d
211d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
211e0 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66  hat was.** the f
211f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
21200 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
21210 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
21220 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74  ts variants.** t
21230 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20  hat was used to 
21240 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
21250 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
21260 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
21270 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
21280 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
21290 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  tmt*);.../*.** C
212a0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
212b0 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
212c0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
212d0 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a  cks {F12950}.**.
212e0 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20  ** {F12951} The 
212f0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
21300 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
21310 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
21320 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
21330 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
21340 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
21350 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
21360 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20  ed..** {F12952} 
21370 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
21380 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
21390 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
213a0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
213b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
213c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
213d0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
213e0 2a 2a 20 7b 46 31 32 39 35 33 7d 20 54 68 65 20  ** {F12953} The 
213f0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
21400 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
21410 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
21420 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
21430 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
21440 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
21450 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69  saction is commi
21460 74 74 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 35 34  tted..** {F12954
21470 7d 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  } Any callback s
21480 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
21490 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
214a0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
214b0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
214c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
214d0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
214e0 2e 0a 2a 2a 20 7b 46 31 32 39 35 36 7d 20 54 68  ..** {F12956} Th
214f0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
21500 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
21510 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  h.** to the call
21520 62 61 63 6b 2e 20 20 7b 46 31 32 39 35 37 7d 20  back.  {F12957} 
21530 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
21540 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
21550 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65   function .** re
21560 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
21570 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
21580 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
21590 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
215a0 0a 2a 2a 20 7b 46 31 32 39 35 38 7d 20 49 66 20  .** {F12958} If 
215b0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
215c0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
215d0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a  registered, its.
215e0 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ** pArg value is
215f0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
21600 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
21610 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  turned..**.** {F
21620 31 32 39 35 39 7d 20 52 65 67 69 73 74 65 72 69  12959} Registeri
21630 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
21640 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
21650 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
21660 7b 46 31 32 39 36 31 7d 20 46 6f 72 20 74 68 65  {F12961} For the
21670 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
21680 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
21690 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
216a0 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f  have been .** ro
216b0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
216c0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
216d0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
216e0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
216f0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
21700 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
21710 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
21720 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
21730 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20 72 6f   {F12962} The ro
21740 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
21750 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
21760 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
21770 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
21780 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
21790 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
217a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
217b0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 7b 46  is closed..** {F
217c0 31 32 39 36 34 7d 20 54 68 65 20 72 6f 6c 6c 62  12964} The rollb
217d0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
217e0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
217f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
21800 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
21810 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
21820 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
21830 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c  d non-zero..** <
21840 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74  todo> Check on t
21850 68 69 73 20 3c 2f 74 6f 64 6f 3e 20 7b 45 4e 44  his </todo> {END
21860 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  }.**.** These ar
21870 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  e experimental i
21880 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 61 72  nterfaces and ar
21890 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
218a0 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  nge..*/.void *sq
218b0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
218c0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
218d0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
218e0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
218f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
21900 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
21910 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
21920 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21930 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
21940 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
21950 62 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a  backs {F12970}.*
21960 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68  *.** {F12971} Th
21970 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
21980 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
21990 65 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61  e.** registers a
219a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
219b0 6f 6e 20 77 69 74 68 20 74 68 65 20 64 61 74 61  on with the data
219c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
219d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
219e0 65 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  e .** first argu
219f0 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ment to be invok
21a00 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
21a10 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
21a20 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
21a30 64 2e 0a 2a 2a 20 7b 46 31 32 39 37 32 7d 20 41  d..** {F12972} A
21a40 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
21a50 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
21a60 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
21a70 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ion for the same
21a80 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f   .** database co
21a90 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
21aa0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ridden..**.** {F
21ab0 31 32 39 37 34 7d 20 54 68 65 20 73 65 63 6f 6e  12974} The secon
21ac0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
21ad0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
21ae0 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
21af0 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77  e when a .** row
21b00 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
21b10 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
21b20 2e 20 0a 2a 2a 20 7b 46 31 32 39 37 36 7d 20 54  . .** {F12976} T
21b30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
21b40 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
21b50 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f  k is.** a copy o
21b60 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
21b70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
21b80 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
21b90 2a 20 7b 46 31 32 39 37 37 7d 20 54 68 65 20 73  * {F12977} The s
21ba0 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a  econd callback .
21bb0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ** argument is o
21bc0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
21bd0 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
21be0 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54  ELETE] or [SQLIT
21bf0 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65  E_UPDATE],.** de
21c00 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
21c10 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
21c20 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
21c30 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  k to be invoked.
21c40 0a 2a 2a 20 7b 46 31 32 39 37 38 7d 20 54 68 65  .** {F12978} The
21c50 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66   third and .** f
21c60 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
21c70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
21c80 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
21c90 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
21ca0 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e   and .** table n
21cb0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
21cc0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
21cd0 0a 2a 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65  .** {F12979} The
21ce0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
21cf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a  parameter is .**
21d00 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
21d10 65 20 72 6f 77 2e 0a 2a 2a 20 7b 46 31 32 39 38  e row..** {F1298
21d20 31 7d 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  1} In the case o
21d30 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
21d40 73 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61  s is the rowid a
21d50 66 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64  fter .** the upd
21d60 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
21d70 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20  .**.** {F12983} 
21d80 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
21d90 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
21da0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
21db0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
21dc0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
21dd0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
21de0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
21df0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ce)..**.** {F129
21e00 38 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 66  84} If another f
21e10 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
21e20 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
21e30 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75  d, its pArg valu
21e40 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  e.** is returned
21e50 2e 20 20 7b 46 31 32 39 38 35 7d 20 4f 74 68 65  .  {F12985} Othe
21e60 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
21e70 74 75 72 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  turned..*/.void 
21e80 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
21e90 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
21ea0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
21eb0 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
21ec0 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
21ed0 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
21ee0 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
21ef0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
21f00 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
21f10 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
21f20 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a  ache {F10330}.**
21f30 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 0a 2a 2a 20  .** {F10331}.** 
21f40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
21f50 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
21f60 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
21f70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
21f80 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
21f90 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
21fa0 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74   between connect
21fb0 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65  ions to the same
21fc0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 7b 46   database..** {F
21fd0 31 30 33 33 32 7d 0a 2a 2a 20 53 68 61 72 69 6e  10332}.** Sharin
21fe0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
21ff0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
22000 74 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65  true and disable
22010 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
22020 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a  t.** is false..*
22030 2a 0a 2a 2a 20 7b 46 31 30 33 33 33 7d 20 43 61  *.** {F10333} Ca
22040 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
22050 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
22060 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e  led.** for an en
22070 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45  tire process. {E
22080 4e 44 7d 20 54 68 69 73 20 69 73 20 61 20 63 68  ND} This is a ch
22090 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
220a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
220b0 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .** In prior ver
220c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
220d0 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20   sharing was.** 
220e0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
220f0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
22100 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
22110 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 34 7d 0a 2a  **.** {F10334}.*
22120 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
22130 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
22140 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
22150 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
22160 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
22170 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
22180 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
22190 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
221a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
221b0 0a 2a 2a 20 7b 46 31 30 33 33 35 7d 20 45 78 69  .** {F10335} Exi
221c0 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
221d0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
221e0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
221f0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
22200 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
22210 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
22220 77 65 72 65 20 6f 70 65 6e 65 64 2e 20 7b 45 4e  were opened. {EN
22230 44 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  D}.**.** Virtual
22240 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
22250 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
22260 61 72 65 64 20 63 61 63 68 65 2e 20 20 7b 46 31  ared cache.  {F1
22270 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65  0336} When share
22280 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
22290 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69  abled, the [sqli
222a0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
222b0 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f  e()] API used to
222c0 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72   register.** vir
222d0 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c  tual tables will
222e0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
222f0 6e 20 65 72 72 6f 72 2e 20 7b 45 4e 44 7d 0a 2a  n error. {END}.*
22300 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54 68  *.** {F10337} Th
22310 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
22320 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ns [SQLITE_OK] i
22330 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
22340 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72  as.** enabled or
22350 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
22360 73 66 75 6c 6c 79 2e 20 20 7b 46 31 30 33 33 38  sfully.  {F10338
22370 7d 20 41 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  } An [SQLITE_ERR
22380 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
22390 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
223a0 6f 74 68 65 72 77 69 73 65 2e 20 7b 45 4e 44 7d  otherwise. {END}
223b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20  .**.** {F10339} 
223c0 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
223d0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
223e0 75 6c 74 2e 20 7b 45 4e 44 7d 20 42 75 74 20 74  ult. {END} But t
223f0 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
22400 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
22410 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
22420 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
22430 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
22440 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
22450 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
22460 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
22470 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22480 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
22490 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
224a0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74  * CAPI3REF:  Att
224b0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
224c0 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30  p Memory {F17340
224d0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d  }.**.** {F17341}
224e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c   The sqlite3_rel
224f0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
22500 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
22510 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79   to.** free N by
22520 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  tes of heap memo
22530 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
22540 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
22550 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
22560 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74  ations held by t
22570 68 65 20 64 61 74 61 62 61 73 65 20 6c 61 62 72  he database labr
22580 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f  ary. {END}  Memo
22590 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61  ry used.** to ca
225a0 63 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  che database pag
225b0 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65  es to improve pe
225c0 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20  rformance is an 
225d0 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f  example of.** no
225e0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
225f0 72 79 2e 20 20 7b 46 31 36 33 34 32 7d 20 73 71  ry.  {F16342} sq
22600 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
22610 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a  mory() returns.*
22620 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
22630 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
22640 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68  reed, which migh
22650 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
22660 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d  s.** than the am
22670 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
22680 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
22690 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
226a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
226b0 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c  REF:  Impose A L
226c0 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
226d0 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a  e {F17350}.**.**
226e0 20 7b 46 31 36 33 35 31 7d 20 54 68 65 20 73 71   {F16351} The sq
226f0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
22700 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
22710 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61 20 22 73  e.** places a "s
22720 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68  oft" limit on th
22730 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
22740 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
22750 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a   be allocated.**
22760 20 62 79 20 53 51 4c 69 74 65 2e 20 7b 46 31 36   by SQLite. {F16
22770 33 35 32 7d 20 49 66 20 61 6e 20 69 6e 74 65 72  352} If an inter
22780 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
22790 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20  s requested .** 
227a0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
227b0 64 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  d the soft heap 
227c0 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
227d0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
227e0 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  ] is.** invoked 
227f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
22800 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
22810 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
22820 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  he allocation.**
22830 20 69 73 20 6d 61 64 65 2e 20 7b 45 4e 44 7d 0a   is made. {END}.
22840 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 54  **.** {F16353} T
22850 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c  he limit is call
22860 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75  ed "soft", becau
22870 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  se if.** [sqlite
22880 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
22890 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72  ()] cannot.** fr
228a0 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  ee sufficient me
228b0 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20  mory to prevent 
228c0 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62  the limit from b
228d0 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a  eing exceeded,.*
228e0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  * the memory is 
228f0 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79  allocated anyway
22900 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
22910 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
22920 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  eds..**.** {F163
22930 35 34 7d 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76  54}.** A negativ
22940 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
22950 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74  for N means that
22960 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66   there is no sof
22970 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
22980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
22990 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
229a0 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ill only be call
229b0 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
229c0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
229d0 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66  {F16355} The def
229e0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
229f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
22a00 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
22a10 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  * SQLite makes a
22a20 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20   best effort to 
22a30 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68  honor the soft h
22a40 65 61 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20  eap limit.  .** 
22a50 7b 46 31 36 33 35 36 7d 20 42 75 74 20 69 66 20  {F16356} But if 
22a60 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
22a70 6d 69 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72  mit cannot honor
22a80 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69  ed, execution wi
22a90 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77  ll.** continue w
22aa0 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20  ithout error or 
22ab0 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 7b 45  notification. {E
22ac0 4e 44 7d 20 20 54 68 69 73 20 69 73 20 77 68 79  ND}  This is why
22ad0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a   the limit is .*
22ae0 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
22af0 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
22b00 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
22b10 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
22b20 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
22b30 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
22b40 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
22b50 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
22b60 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
22b70 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
22b80 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
22b90 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
22ba0 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
22bb0 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
22bc0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
22bd0 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
22be0 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
22bf0 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
22c00 65 61 64 73 2e 20 7b 46 31 36 33 35 37 7d 20 54  eads. {F16357} T
22c10 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
22c20 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
22c30 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
22c40 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
22c50 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
22c60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
22c70 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
22c80 7b 45 4e 44 7d 20 20 49 6e 0a 2a 2a 20 76 65 72  {END}  In.** ver
22c90 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65  sion 3.5.0 there
22ca0 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d   is no mechanism
22cb0 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68   for limiting th
22cc0 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72  e heap usage for
22cd0 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74  .** individual t
22ce0 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20  hreads..*/.void 
22cf0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
22d00 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f  p_limit(int);../
22d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
22d20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
22d30 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
22d40 4f 66 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38  Of A Table {F128
22d50 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  50}.**.** This r
22d60 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e  outine.** return
22d70 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75  s meta-data abou
22d80 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
22d90 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
22da0 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  c database.** ta
22db0 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
22dc0 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
22dd0 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65  ion handle passe
22de0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
22df0 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75  unction .** argu
22e00 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
22e10 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
22e20 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
22e30 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
22e40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
22e50 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  to .** this func
22e60 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
22e70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
22e80 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
22e90 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
22ea0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
22eb0 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
22ec0 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
22ed0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
22ee0 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
22ef0 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
22f00 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
22f10 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
22f20 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
22f30 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
22f40 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
22f50 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74  e algorithm as t
22f60 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
22f70 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72  ne uses to .** r
22f80 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
22f90 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
22fa0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ces..**.** The t
22fb0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
22fc0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
22fd0 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
22fe0 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
22ff0 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66  lumn .** name of
23000 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
23010 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
23020 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
23030 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a  ese parameters .
23040 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a  ** may be NULL..
23050 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72  **.** Meta infor
23060 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  mation is return
23070 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
23080 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
23090 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a  tions passed as.
230a0 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73  ** the 5th and s
230b0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
230c0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
230d0 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68  ction. Any of th
230e0 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ese .** argument
230f0 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69  s may be NULL, i
23100 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
23110 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
23120 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a  lement of meta .
23130 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
23140 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  s ommitted..**.*
23150 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d  * <pre>.** Param
23160 65 74 65 72 20 20 20 20 20 4f 75 74 70 75 74 20  eter     Output 
23170 54 79 70 65 20 20 20 20 20 20 44 65 73 63 72 69  Type      Descri
23180 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d  ption.** -------
23190 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
231a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a  ------------.**.
231b0 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20 20 20  **   5th        
231c0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20   const char*    
231d0 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20    Data type.**  
231e0 20 36 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e   6th         con
231f0 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61  st char*      Na
23200 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  me of the defaul
23210 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
23220 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20  ence .**   7th  
23230 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20         int      
23240 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20          True if 
23250 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61  the column has a
23260 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
23270 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20  aint.**   8th   
23280 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
23290 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
232a0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  he column is par
232b0 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
232c0 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20   KEY.**   9th   
232d0 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
232e0 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
232f0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54  he column is AUT
23300 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f  OINCREMENT.** </
23310 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  pre>.**.**.** Th
23320 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
23330 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
23340 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
23350 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a  turned for the .
23360 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
23370 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
23380 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
23390 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
233a0 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c  he next .** call
233b0 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41   to any sqlite A
233c0 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
233d0 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
233e0 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
233f0 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68  ually a view, th
23400 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  en an error is r
23410 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
23420 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
23430 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
23440 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
23450 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a  wid_" and an .**
23460 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
23470 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20   KEY column has 
23480 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
23490 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
234a0 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61  he output .** pa
234b0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
234c0 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
234d0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
234e0 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
234f0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
23500 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63  y declared IPK c
23510 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20  olumn, then the 
23520 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 72  output parameter
23530 73 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a  s are set as .**
23540 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
23550 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
23560 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
23570 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
23580 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
23590 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
235a0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
235b0 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
235c0 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
235d0 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
235e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
235f0 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
23600 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
23610 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
23620 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
23630 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
23640 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
23650 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
23660 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
23670 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
23680 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51   be found, an SQ
23690 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20  LITE error code 
236a0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
236b0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
236c0 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20  .** left in the 
236d0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
236e0 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
236f0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
23700 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20  rrmsg())..**.** 
23710 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
23720 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
23730 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
23740 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
23750 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
23760 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
23770 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
23780 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
23790 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
237a0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
237b0 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
237c0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
237d0 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
237e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
237f0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
23800 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
23810 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
23820 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23830 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
23840 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
23850 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
23860 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
23870 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
23880 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
23890 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
238a0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
238b0 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
238c0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
238d0 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
238e0 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
238f0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
23900 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
23910 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
23920 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
23930 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
23940 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
23950 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
23960 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
23970 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
23980 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
23990 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
239a0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
239b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
239c0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
239d0 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
239e0 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
239f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
23a00 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
23a10 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12600}.**.** {F1
23a20 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65  2601} The sqlite
23a30 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
23a40 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
23a50 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64  attempts to load
23a60 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
23a70 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e  sion library con
23a80 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69  tained in the fi
23a90 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31  le.** zFile. {F1
23aa0 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20  2602} The entry 
23ab0 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20  point is zProc. 
23ac0 7b 46 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d  {F12603} zProc m
23ad0 61 79 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68  ay be 0.** in wh
23ae0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
23af0 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
23b00 6f 69 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a  oint defaults.**
23b10 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
23b20 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
23b30 0a 2a 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65  .** {F12604} The
23b40 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
23b50 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
23b60 61 63 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74  ace shall.** ret
23b70 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
23b80 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
23b90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
23ba0 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
23bb0 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  wrong..**.** {F1
23bc0 32 36 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65  2605}.** If an e
23bd0 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
23be0 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
23bf0 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73  0, then the.** s
23c00 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
23c10 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
23c20 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20  e shall attempt 
23c30 74 6f 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73  to fill *pzErrMs
23c40 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72  g with .** error
23c50 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
23c60 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  ored in memory o
23c70 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
23c80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
23c90 0a 2a 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63  .** {END}  The c
23ca0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
23cb0 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
23cc0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61   memory.** by ca
23cd0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
23ce0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ree()]..**.** {F
23cf0 31 32 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73  12606}.** Extens
23d00 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
23d10 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
23d20 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
23d30 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
23d40 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
23d50 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49  calling this API
23d60 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c   or an error wil
23d70 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a  l be returned..*
23d80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
23d90 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
23da0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
23db0 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
23dc0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
23dd0 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
23de0 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
23df0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
23e00 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
23e10 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
23e20 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
23e30 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
23e40 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
23e50 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
23e60 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
23e70 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
23e80 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
23e90 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
23ea0 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
23eb0 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
23ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23ed0 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
23ee0 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
23ef0 61 64 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a  ading {F12620}.*
23f00 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74  *.** So as not t
23f10 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
23f20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
23f30 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
23f40 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
23f50 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
23f60 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
23f70 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
23f80 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
23f90 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
23fa0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
23fb0 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
23fc0 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
23fd0 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70  wing.** API is p
23fe0 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
23ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
24000 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
24010 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a  echanism on and.
24020 2a 2a 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32  ** off.  {F12622
24030 7d 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64  } It is off by d
24040 65 66 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65  efault. {END} Se
24050 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a  e ticket #1863..
24060 2a 2a 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43  **.** {F12621} C
24070 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
24080 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
24090 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a  nsion() routine.
240a0 2a 2a 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ** with onoff==1
240b0 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
240c0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a  on loading on.**
240d0 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74   and call it wit
240e0 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75  h onoff==0 to tu
240f0 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  rn it back off a
24100 67 61 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69  gain. {END}.*/.i
24110 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
24120 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
24130 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e  (sqlite3 *db, in
24140 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
24150 20 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20   CAPI3REF: Make 
24160 41 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20  Arrangements To 
24170 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
24180 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20  ad An Extension 
24190 7b 46 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12640}.**.** {
241a0 46 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e  F12641} This fun
241b0 63 74 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65  ction.** registe
241c0 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  rs an extension 
241d0 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
241e0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
241f0 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  y invoked.** whe
24200 6e 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61  never a new data
24210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24220 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a  is opened using.
24230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
24240 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
24250 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
24260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
24270 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
24280 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
24290 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
242a0 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
242b0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
242c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
242d0 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
242e0 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
242f0 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
24300 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61  ** to all new da
24310 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24320 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34  ns..**.** {F1264
24330 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 74  2} Duplicate ext
24340 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65  ensions are dete
24350 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20  cted so calling 
24360 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c  this routine mul
24370 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
24380 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
24390 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
243a0 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34  ss..**.** {F1264
243b0 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  3} This routine 
243c0 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72  stores a pointer
243d0 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f   to the extensio
243e0 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a  n in an array.**
243f0 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65   that is obtaine
24400 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61  d from sqlite_ma
24410 6c 6c 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66  lloc(). {END} If
24420 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72   you run a memor
24430 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65  y leak.** checke
24440 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61  r on your progra
24450 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73  m and it reports
24460 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20   a leak because 
24470 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79  of this.** array
24480 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73  , then invoke [s
24490 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
244a0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70  o_extension()] p
244b0 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64  rior.** to shutd
244c0 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
244d0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  memory..**.** {F
244e0 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63  12644} Automatic
244f0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
24500 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
24510 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  eads. {END}.**.*
24520 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
24530 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
24540 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
24550 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
24560 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
24570 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
24580 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
24590 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
245a0 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79  ion(void *xEntry
245b0 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  Point);.../*.** 
245c0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
245d0 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
245e0 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32  ion Loading {F12
245f0 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  660}.**.** {F126
24600 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f  61} This functio
24610 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
24620 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
24630 65 72 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  ered.** automati
24640 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45  c extensions. {E
24650 4e 44 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75  ND}  This.** rou
24660 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
24670 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
24680 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  ior [sqlite3_aut
24690 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e  omatic_extension
246a0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a  ()].** calls..**
246b0 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69  .** {F12662} Thi
246c0 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20  s call disabled 
246d0 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
246e0 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65  ions in all thre
246f0 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ads. {END}.**.**
24700 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
24710 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
24720 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
24730 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72  o change or.** r
24740 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
24750 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
24760 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ite..*/.void sql
24770 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
24780 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b  extension(void);
24790 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  .../*.****** EXP
247a0 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
247b0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
247c0 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
247d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
247e0 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
247f0 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
24800 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
24810 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
24820 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
24830 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
24840 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
24850 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
24860 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
24870 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
24880 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
24890 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
248a0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
248b0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
248c0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
248d0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
248e0 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  tablizes, we wil
248f0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
24900 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
24910 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
24920 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
24930 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
24940 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
24950 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
24960 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
24970 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
24980 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
24990 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
249a0 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
249b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
249c0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
249d0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
249e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
249f0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
24a00 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
24a10 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
24a20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
24a30 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
24a40 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d  dule;../*.** A m
24a50 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73  odule is a class
24a60 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c   of virtual tabl
24a70 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  es.  Each module
24a80 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62   is defined.** b
24a90 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  y an instance of
24aa0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
24ab0 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20  tructure.  This 
24ac0 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
24ad0 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20  ts.** mostly of 
24ae0 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
24af0 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63  module..*/.struc
24b00 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
24b10 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
24b20 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
24b30 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
24b40 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
24b50 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
24b60 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
24b70 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
24b80 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
24b90 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
24ba0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
24bb0 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
24bc0 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
24bd0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
24be0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
24bf0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
24c00 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
24c10 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
24c20 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
24c30 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
24c40 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
24c50 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
24c60 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
24c70 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
24c80 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
24c90 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
24ca0 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
24cb0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
24cc0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
24cd0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
24ce0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
24cf0 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
24d00 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
24d10 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
24d20 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
24d30 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
24d40 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
24d50 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
24d60 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
24d70 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
24d80 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
24d90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
24da0 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
24db0 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
24dc0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
24dd0 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
24de0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
24df0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
24e00 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
24e10 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
24e20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
24e30 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
24e40 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
24e50 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
24e60 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
24e70 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
24e80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
24e90 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
24ea0 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
24eb0 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
24ec0 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
24ed0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
24ee0 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
24ef0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
24f00 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
24f10 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
24f20 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
24f30 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
24f40 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
24f50 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
24f60 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
24f70 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
24f80 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
24f90 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
24fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24fb0 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
24fc0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
24fd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
24fe0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
24ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25000 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
25010 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61  ;..  int (*xRena
25020 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  me)(sqlite3_vtab
25030 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63   *pVtab, const c
25040 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a  har *zNew);.};..
25050 2f 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  /*.** The sqlite
25060 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
25070 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
25080 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
25090 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20  used to.** pass 
250a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
250b0 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
250c0 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
250d0 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65  xBestIndex.** me
250e0 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74  thod of an sqlit
250f0 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  e3_module.  The 
25100 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
25110 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
25120 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
25130 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
25140 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
25150 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
25160 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
25170 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
25180 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
25190 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
251a0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
251b0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
251c0 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
251d0 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  .** form:.**.** 
251e0 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f          column O
251f0 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65  P expr.**.** Whe
25200 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
25210 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
25220 72 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68  r &gt;=.  .** Th
25230 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
25240 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a  rator is stored.
25250 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ** in aConstrain
25260 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64  t[].op.  The ind
25270 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
25280 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a   is stored in .*
25290 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
252a0 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74  iColumn.  aConst
252b0 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
252c0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
252d0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
252e0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
252f0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
25300 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
25310 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
25320 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
25330 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a  f it cannot..**.
25340 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72  ** The optimizer
25350 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
25360 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20  nverts terms of 
25370 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f  the form "expr O
25380 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64  P column".** and
25390 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d   makes other sim
253a0 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20  plifications to 
253b0 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
253c0 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74   in an attempt t
253d0 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79  o.** get as many
253e0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
253f0 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72  rms into the for
25400 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73  m shown above as
25410 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68   possible..** Th
25420 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
25430 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
25440 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
25450 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72  terms in the cor
25460 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61  rect.** form tha
25470 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70  t refer to the p
25480 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
25490 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
254a0 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66  eried..**.** Inf
254b0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
254c0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
254d0 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
254e0 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45  aOrderBy[]..** E
254f0 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
25500 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
25510 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
25520 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
25530 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64  .** The xBestInd
25540 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66  ex method must f
25550 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  ill aConstraintU
25560 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f  sage[] with info
25570 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
25580 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73   what parameters
25590 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c   to pass to xFil
255a0 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64  ter.  If argvInd
255b0 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
255c0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
255d0 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
255e0 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
255f0 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
25600 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
25610 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
25620 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
25630 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55   If aConstraintU
25640 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
25650 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
25660 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
25670 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
25680 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
25690 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
256a0 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
256b0 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
256c0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
256d0 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
256e0 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
256f0 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
25700 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a  d into xFilter..
25710 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
25720 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65  ) is used to fre
25730 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64  e idxPtr if need
25740 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20  ToFreeIdxPtr is 
25750 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  true..**.** The 
25760 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
25770 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75  means that outpu
25780 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77  t from xFilter w
25790 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
257a0 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
257b0 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
257c0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
257d0 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
257e0 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
257f0 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
25800 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69  ..**.** The esti
25810 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
25820 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
25830 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
25840 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
25850 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
25860 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
25870 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
25880 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
25890 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
258a0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
258b0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
258c0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
258d0 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
258e0 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
258f0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
25900 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
25910 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
25920 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
25930 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
25940 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
25950 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
25960 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
25970 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
25980 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
25990 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
259a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
259b0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
259c0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
259d0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
259e0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
259f0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
25a00 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
25a10 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
25a20 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
25a30 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
25a40 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
25a50 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
25a60 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
25a70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
25a80 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
25a90 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
25aa0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
25ab0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
25ac0 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
25ad0 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
25ae0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
25af0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
25b00 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25b10 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
25b20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
25b30 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
25b40 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
25b50 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
25b60 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
25b70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
25b80 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
25b90 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
25ba0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
25bb0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
25bc0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
25bd0 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
25be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
25bf0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
25c00 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f  lause */..  /* O
25c10 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
25c20 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
25c30 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
25c40 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
25c50 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
25c60 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
25c70 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
25c80 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
25c90 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
25ca0 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
25cb0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
25cc0 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
25cd0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
25ce0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
25cf0 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
25d00 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
25d10 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
25d20 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
25d30 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
25d40 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
25d50 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
25d60 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
25d70 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
25d80 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
25d90 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
25da0 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
25db0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
25dc0 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
25dd0 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
25de0 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
25df0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
25e00 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
25e10 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
25e20 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
25e30 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
25e40 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
25e50 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
25e60 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  /.};.#define SQL
25e70 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
25e80 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
25e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
25ea0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
25eb0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
25ec0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
25ed0 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
25ee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
25ef0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
25f00 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
25f10 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
25f20 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
25f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
25f40 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
25f50 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54  ATCH 64../*.** T
25f60 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
25f70 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
25f80 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d  a new module nam
25f90 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65  e with an SQLite
25fa0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
25fb0 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75   Module names mu
25fc0 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
25fd0 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67   before creating
25fe0 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20   new.** virtual 
25ff0 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f  tables on the mo
26000 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  dule, or before 
26010 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e  using preexistin
26020 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  g virtual.** tab
26030 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  les of the modul
26040 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
26050 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
26060 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
26070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26080 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
26090 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
260a0 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
260b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
260c0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
260d0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
260e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
260f0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20  te3_module *,   
26100 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
26110 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
26120 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20  void *          
26130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c             /* Cl
26140 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
26150 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
26160 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73  /.);../*.** This
26170 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e   routine is iden
26180 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c  tical to the sql
26190 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
261a0 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76  le() method abov
261b0 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  e,.** except tha
261c0 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65  t it allows a de
261d0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
261e0 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 65  n to be specifie
261f0 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e  d. It is.** even
26200 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74   more experiment
26210 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 74  al than the rest
26220 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
26230 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69  tables API..*/.i
26240 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26250 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
26260 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
26270 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
26280 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
26290 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
262a0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
262b0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
262c0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
262d0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
262e0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
262f0 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20  module *,    /* 
26300 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
26310 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
26320 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
26330 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
26340 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
26350 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
26360 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
26370 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
26380 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
26390 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
263a0 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75  /*.** Every modu
263b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
263c0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
263d0 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  s of the followi
263e0 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  ng structure.** 
263f0 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
26400 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
26410 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  e of the module.
26420 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20    Each subclass 
26430 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f  will.** be tailo
26440 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69  red to the speci
26450 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65  fic needs of the
26460 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
26470 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a  tation.   The.**
26480 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
26490 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
264a0 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
264b0 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
264c0 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c   common.** to al
264d0 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
264e0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
264f0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
26500 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
26510 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
26520 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
26530 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
26540 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
26550 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72  printf() to zErr
26560 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64  Msg.  The method
26570 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20   should.** take 
26580 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72  care that any pr
26590 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72  ior string is fr
265a0 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  eed by a call to
265b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a   sqlite3_free().
265c0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
265d0 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
265e0 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
265f0 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  After the error 
26600 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65  message.** is de
26610 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68  livered up to th
26620 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61  e client applica
26630 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67  tion, the string
26640 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
26650 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20  ically.** freed 
26660 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  by sqlite3_free(
26670 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73  ) and the zErrMs
26680 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20  g field will be 
26690 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a  zeroed.  Note.**
266a0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70   that sqlite3_mp
266b0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
266c0 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 75  te3_free() are u
266d0 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d  sed on the zErrM
266e0 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63  sg field.** sinc
266f0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
26700 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d   are commonly im
26710 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61  plemented in loa
26720 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73  dable extensions
26730 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74   which.** do not
26740 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f 20   have access to 
26750 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29  sqlite3MPrintf()
26760 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 28   or sqlite3Free(
26770 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  )..*/.struct sql
26780 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
26790 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
267a0 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
267b0 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
267c0 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
267d0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
267e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
267f0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
26800 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20  internally */.  
26810 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
26820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26830 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
26840 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
26850 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
26860 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
26870 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
26880 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
26890 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
268a0 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65  ds */.};../* Eve
268b0 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
268c0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
268d0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
268e0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
268f0 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
26900 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20  be cursors that 
26910 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76  point into the v
26920 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
26930 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
26940 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
26950 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
26960 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
26970 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
26980 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f  * xOpen method o
26990 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45  f the module.  E
269a0 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ach module imple
269b0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64  mentation will d
269c0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e  efine.** the con
269d0 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72  tent of a cursor
269e0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75   structure to su
269f0 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73  it its own needs
26a00 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70  ..**.** This sup
26a10 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69  erclass exists i
26a20 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e  n order to defin
26a30 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  e fields of the 
26a40 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61  cursor that.** a
26a50 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  re common to all
26a60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
26a70 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
26a80 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
26a90 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62  {.  sqlite3_vtab
26aa0 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a   *pVtab;      /*
26ab0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   Virtual table o
26ac0 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f  f this cursor */
26ad0 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
26ae0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
26af0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
26b00 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
26b10 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
26b20 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74  /*.** The xCreat
26b30 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d  e and xConnect m
26b40 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75  ethods of a modu
26b50 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f  le use the follo
26b60 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64  wing API.** to d
26b70 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
26b80 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
26b90 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
26ba0 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
26bb0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
26bc0 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
26bd0 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
26be0 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
26bf0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
26c00 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62  char *zCreateTab
26c10 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74  le);../*.** Virt
26c20 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
26c30 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
26c40 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
26c50 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
26c60 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69  ** using the xFi
26c70 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f  ndFunction metho
26c80 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76  d.  But global v
26c90 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65  ersions of those
26ca0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75   functions.** mu
26cb0 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65  st exist in orde
26cc0 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64  r to be overload
26cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ed..**.** This A
26ce0 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
26cf0 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
26d00 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
26d10 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
26d20 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
26d30 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
26d40 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
26d50 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
26d60 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
26d70 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
26d80 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
26d90 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68   is created.  Th
26da0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
26db0 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66  .** of the new f
26dc0 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63  unction always c
26dd0 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69  auses an excepti
26de0 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e  on to be thrown.
26df0 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20    So.** the new 
26e00 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
26e10 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e  good for anythin
26e20 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74  g by itself.  It
26e30 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73  s only.** purpos
26e40 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61  e is to be a pla
26e50 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69  ce-holder functi
26e60 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  on that can be o
26e70 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20  verloaded.** by 
26e80 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a  virtual tables..
26e90 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73  **.** This API s
26ea0 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65  hould be conside
26eb0 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20  red part of the 
26ec0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
26ed0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63  terface,.** whic
26ee0 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  h is experimenta
26ef0 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f  l and subject to
26f00 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
26f10 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
26f20 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
26f30 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
26f40 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
26f50 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
26f60 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
26f70 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
26f80 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
26f90 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
26fa0 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
26fb0 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
26fc0 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
26fd0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
26fe0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
26ff0 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
27000 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
27010 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
27020 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
27030 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
27040 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
27050 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
27060 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
27070 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
27080 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
27090 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
270a0 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
270b0 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
270c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
270d0 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
270e0 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
270f0 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
27100 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
27110 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
27120 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
27130 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
27140 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
27150 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
27160 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
27170 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31  An Open BLOB {F1
27180 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  7800}.**.** An i
27190 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66  nstance of the f
271a0 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20  ollowing opaque 
271b0 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73 65  structure is use
271c0 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65  d to .** represe
271d0 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c  nt an blob-handl
271e0 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c  e.  A blob-handl
271f0 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 0a  e is created by.
27200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
27210 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73  _open()] and des
27220 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
27230 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
27240 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
27250 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
27260 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
27270 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
27280 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
27290 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
272a0 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
272b0 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c  ctions of the bl
272c0 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  ob..** The [sqli
272d0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
272e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
272f0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
27300 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62  the.** blob in b
27310 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
27320 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
27330 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
27340 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
27350 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
27360 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
27370 49 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a  I/O {F17810}.**.
27380 2a 2a 20 7b 46 31 37 38 31 31 7d 20 54 68 69 73  ** {F17811} This
27390 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e   interfaces open
273a0 73 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68  s a handle to th
273b0 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a  e blob located.*
273c0 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20  * in row iRow,, 
273d0 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
273e0 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20  table zTable in 
273f0 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a  database zDb;.**
27400 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
27410 20 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20    the same blob 
27420 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65  that would be se
27430 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a  lected by:.**.**
27440 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45   <pre>.**     SE
27450 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f  LECT zColumn FRO
27460 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45  M zDb.zTable WHE
27470 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b  RE rowid = iRow;
27480 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d  .** </pre> {END}
27490 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 32 7d 20  .**.** {F17812} 
274a0 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  If the flags par
274b0 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65  ameter is non-ze
274c0 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20  ro, the blob is 
274d0 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72  opened for .** r
274e0 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63  ead and write ac
274f0 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a  cess. If it is z
27500 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73  ero, the blob is
27510 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
27520 20 0a 2a 2a 20 61 63 63 65 73 73 2e 20 7b 45 4e   .** access. {EN
27530 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33  D}.**.** {F17813
27540 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  } On success, [S
27550 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
27560 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
27570 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  w .** [sqlite3_b
27580 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
27590 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  e] is written to
275a0 20 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 7b 46   *ppBlob. .** {F
275b0 31 37 38 31 34 7d 20 4f 74 68 65 72 77 69 73 65  17814} Otherwise
275c0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
275d0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a  s returned and .
275e0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69  ** any value wri
275f0 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20  tten to *ppBlob 
27600 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
27610 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
27620 2e 0a 2a 2a 20 7b 46 31 37 38 31 35 7d 20 54 68  ..** {F17815} Th
27630 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
27640 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61   the database-ha
27650 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20  ndle error code 
27660 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61  and message.** a
27670 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
27680 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
27690 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
276a0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3c 74 6f  rrmsg()]..** <to
276b0 64 6f 3e 57 65 20 73 68 6f 75 6c 64 20 67 6f 20  do>We should go 
276c0 74 68 72 6f 75 67 68 20 61 6e 64 20 6d 61 72 6b  through and mark
276d0 20 61 6c 6c 20 69 6e 74 65 72 66 61 63 65 73 20   all interfaces 
276e0 74 68 61 74 20 62 65 68 61 76 65 20 74 68 69 73  that behave this
276f0 0a 2a 2a 20 77 61 79 20 77 69 74 68 20 61 20 73  .** way with a s
27700 69 6d 69 6c 61 72 20 73 74 61 74 65 6d 65 6e 74  imilar statement
27710 3c 2f 74 6f 64 6f 3e 0a 2a 2f 0a 69 6e 74 20 73  </todo>.*/.int s
27720 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
27730 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
27740 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
27750 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
27760 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
27770 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
27780 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
27790 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
277a0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
277b0 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
277c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c  ** CAPI3REF:  Cl
277d0 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
277e0 65 20 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a  e {F17830}.**.**
277f0 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b   Close an open [
27800 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
27810 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  lob handle]..**.
27820 2a 2a 20 7b 46 31 37 38 33 31 7d 20 43 6c 6f 73  ** {F17831} Clos
27830 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c  ing a BLOB shall
27840 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
27850 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
27860 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74  o commit.** if t
27870 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65  here are no othe
27880 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64  r BLOBs, no pend
27890 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
278a0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65  tements, and the
278b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
278c0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75  nection is in au
278d0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a  tocommit mode..*
278e0 2a 20 7b 46 31 37 38 33 32 7d 20 49 66 20 61 6e  * {F17832} If an
278f0 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
27900 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
27910 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
27920 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
27930 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
27940 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
27950 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d   will fit. {END}
27960 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20  .** Closing the 
27970 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65  BLOB often force
27980 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a  s the changes.**
27990 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64   out to disk and
279a0 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65   so if any I/O e
279b0 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65  rrors occur, the
279c0 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63  y will likely oc
279d0 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69  cur.** at the ti
279e0 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42  me when the BLOB
279f0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31   is closed.  {F1
27a00 37 38 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73  7833} Any errors
27a10 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
27a20 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
27a30 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
27a40 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
27a50 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
27a60 37 38 33 39 7d 20 54 68 65 20 42 4c 4f 42 20 69  7839} The BLOB i
27a70 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
27a80 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
27a90 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
27aa0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
27ab0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
27ac0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
27ad0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
27ae0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
27af0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
27b00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27b10 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
27b20 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
27b30 20 7b 46 31 37 38 30 35 7d 0a 2a 2a 0a 2a 2a 20   {F17805}.**.** 
27b40 7b 46 31 36 38 30 36 7d 20 52 65 74 75 72 6e 20  {F16806} Return 
27b50 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
27b60 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63  s of the blob ac
27b70 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
27b80 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
27b90 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
27ba0 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
27bb0 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f   an argument..*/
27bc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
27bd0 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  b_bytes(sqlite3_
27be0 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
27bf0 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64 20  CAPI3REF:  Read 
27c00 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42  Data From A BLOB
27c10 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b   Incrementally {
27c20 46 31 37 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17850}.**.** Th
27c30 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
27c40 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
27c50 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a   from an open .*
27c60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
27c70 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69  | blob-handle] i
27c80 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70  nto a caller sup
27c90 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
27ca0 20 7b 46 31 37 38 35 31 7d 20 6e 20 62 79 74 65   {F17851} n byte
27cb0 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f  s of data are co
27cc0 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72  pied into buffer
27cd0 0a 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f  .** z from the o
27ce0 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69  pen blob, starti
27cf0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
27d00 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  fset..**.** {F17
27d10 38 35 32 7d 20 49 66 20 6f 66 66 73 65 74 20 69  852} If offset i
27d20 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
27d30 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d  han n bytes from
27d40 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
27d50 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  blob, .** [SQLIT
27d60 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
27d70 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
27d80 20 69 73 20 72 65 61 64 2e 20 20 7b 46 31 37 38   is read.  {F178
27d90 35 33 7d 20 49 66 20 6e 20 69 73 0a 2a 2a 20 6c  53} If n is.** l
27da0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53  ess than zero [S
27db0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
27dc0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
27dd0 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
27de0 0a 2a 2a 20 7b 46 31 37 38 35 34 7d 20 4f 6e 20  .** {F17854} On 
27df0 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f  success, SQLITE_
27e00 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
27e10 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a  Otherwise, an .*
27e20 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
27e30 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63  | SQLite error c
27e40 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ode] or an.** [S
27e50 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
27e60 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f   | extended erro
27e70 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
27e80 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
27e90 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71  te3_blob_read(sq
27ea0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f  lite3_blob *, vo
27eb0 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
27ec0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
27ed0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 57 72  ** CAPI3REF:  Wr
27ee0 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20  ite Data Into A 
27ef0 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
27f00 6c 79 20 7b 46 31 37 38 37 30 7d 0a 2a 2a 0a 2a  ly {F17870}.**.*
27f10 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
27f20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65  is used to write
27f30 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70   data into an op
27f40 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
27f50 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64  blob | blob-hand
27f60 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 72 20  le] from a user 
27f70 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
27f80 0a 2a 2a 20 7b 46 31 37 38 37 31 7d 20 6e 20 62  .** {F17871} n b
27f90 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
27fa0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65   copied from the
27fb0 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e 74   buffer.** point
27fc0 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f 20  ed to by z into 
27fd0 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73  the open blob, s
27fe0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
27ff0 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
28000 20 7b 46 31 37 38 37 32 7d 20 49 66 20 74 68 65   {F17872} If the
28010 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
28020 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61   blob-handle] pa
28030 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
28040 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61  t argument.** wa
28050 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72  s not opened for
28060 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c   writing (the fl
28070 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
28080 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
28090 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a  pen()].*** was z
280a0 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74  ero), this funct
280b0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
280c0 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
280d0 2a 0a 2a 2a 20 7b 46 31 37 38 37 33 7d 20 54 68  *.** {F17873} Th
280e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
280f0 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  only modify the 
28100 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
28110 62 6c 6f 62 3b 20 69 74 20 69 73 0a 2a 2a 20 6e  blob; it is.** n
28120 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69  ot possible to i
28130 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65  ncrease the size
28140 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67   of a blob using
28150 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 7b 46   this API..** {F
28160 31 37 38 37 34 7d 20 49 66 20 6f 66 66 73 65 74  17874} If offset
28170 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
28180 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72   than n bytes fr
28190 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
281a0 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c  e blob, .** [SQL
281b0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
281c0 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
281d0 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20  ta is written.  
281e0 7b 46 31 37 38 37 35 7d 20 49 66 20 6e 20 69 73  {F17875} If n is
281f0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
28200 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ro [SQLITE_ERROR
28210 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
28220 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
28230 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  tten..**.** {F17
28240 38 37 36 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c  876} On success,
28250 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
28260 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73  turned. Otherwis
28270 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  e, an .** [SQLIT
28280 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65  E_ERROR | SQLite
28290 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20   error code] or 
282a0 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  an.** [SQLITE_IO
282b0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
282c0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
282d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  is returned..*/.
282e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
282f0 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62  _write(sqlite3_b
28300 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  lob *, const voi
28310 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  d *z, int n, int
28320 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
28330 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69 72  * CAPI3REF:  Vir
28340 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d  tual File System
28350 20 4f 62 6a 65 63 74 73 20 7b 46 31 31 32 30 30   Objects {F11200
28360 7d 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  }.**.** A virtua
28370 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
28380 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
28390 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
283a0 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
283b0 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
283c0 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
283d0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
283e0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69  ystem.  Most bui
283f0 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a  lds come with a.
28400 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c  ** single defaul
28410 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70  t VFS that is ap
28420 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
28430 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
28440 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61  .** New VFSes ca
28450 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
28460 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53  and existing VFS
28470 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69  es can be unregi
28480 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66  stered..** The f
28490 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
284a0 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
284b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 31 7d  ..**.** {F11201}
284c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   The sqlite3_vfs
284d0 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
284e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
284f0 74 65 72 20 74 6f 20 0a 2a 2a 20 61 20 56 46 53  ter to .** a VFS
28500 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
28510 20 20 7b 46 31 31 32 30 32 7d 20 4e 61 6d 65 73    {F11202} Names
28520 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74   are case sensit
28530 69 76 65 2e 0a 2a 2a 20 7b 46 31 31 32 30 33 7d  ive..** {F11203}
28540 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d   Names are zero-
28550 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
28560 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 7b 46 31   strings..** {F1
28570 31 32 30 34 7d 20 49 66 20 74 68 65 72 65 20 69  1204} If there i
28580 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55  s no match, a NU
28590 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  LL.** pointer is
285a0 20 72 65 74 75 72 6e 65 64 2e 20 7b 46 31 31 32   returned. {F112
285b0 30 35 7d 20 49 66 20 7a 56 66 73 4e 61 6d 65 20  05} If zVfsName 
285c0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
285d0 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53   default .** VFS
285e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 45   is returned. {E
285f0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31  ND}.**.** {F1121
28600 30 7d 20 4e 65 77 20 56 46 53 65 73 20 61 72 65  0} New VFSes are
28610 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
28620 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67   sqlite3_vfs_reg
28630 69 73 74 65 72 28 29 2e 0a 2a 2a 20 7b 46 31 31  ister()..** {F11
28640 32 31 31 7d 20 45 61 63 68 20 6e 65 77 20 56 46  211} Each new VF
28650 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65  S becomes the de
28660 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65  fault VFS if the
28670 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69   makeDflt flag i
28680 73 20 73 65 74 2e 0a 2a 2a 20 7b 46 31 31 32 31  s set..** {F1121
28690 32 7d 20 54 68 65 20 73 61 6d 65 20 56 46 53 20  2} The same VFS 
286a0 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
286b0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
286c0 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e   without injury.
286d0 0a 2a 2a 20 7b 46 31 31 32 31 33 7d 20 54 6f 20  .** {F11213} To 
286e0 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67  make an existing
286f0 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65   VFS into the de
28700 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73  fault VFS, regis
28710 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20  ter it again.** 
28720 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c  with the makeDfl
28730 74 20 66 6c 61 67 20 73 65 74 2e 20 7b 55 31 31  t flag set. {U11
28740 32 31 34 7d 20 49 66 20 74 77 6f 20 64 69 66 66  214} If two diff
28750 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68  erent VFSes with
28760 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d   the.** same nam
28770 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  e are registered
28780 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
28790 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 7b 55  s undefined.  {U
287a0 31 31 32 31 35 7d 20 49 66 20 61 0a 2a 2a 20 56  11215} If a.** V
287b0 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
287c0 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
287d0 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
287e0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
287f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
28800 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
28810 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 32 32 30 7d  .** .** {F11220}
28820 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46   Unregister a VF
28830 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
28840 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
28850 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
28860 2a 20 7b 46 31 31 32 32 31 7d 20 49 66 20 74 68  * {F11221} If th
28870 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
28880 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61   unregistered, a
28890 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68  nother VFS is ch
288a0 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64  osen as.** the d
288b0 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f  efault.  The cho
288c0 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20  ice for the new 
288d0 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79  VFS is arbitrary
288e0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73  ..*/.sqlite3_vfs
288f0 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   *sqlite3_vfs_fi
28900 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  nd(const char *z
28910 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71  VfsName);.int sq
28920 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
28930 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  er(sqlite3_vfs*,
28940 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a   int makeDflt);.
28950 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
28960 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  unregister(sqlit
28970 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e3_vfs*);../*.**
28980 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
28990 65 73 20 7b 46 31 37 30 30 30 7d 0a 2a 2a 0a 2a  es {F17000}.**.*
289a0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
289b0 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  e uses these rou
289c0 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64  tines for thread
289d0 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74  .** synchronizat
289e0 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65  ion.  Though the
289f0 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  y are intended f
28a00 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
28a10 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f  se by SQLite, co
28a20 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  de that links ag
28a30 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
28a40 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  ** permitted to 
28a50 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
28a60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
28a70 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   The SQLite sour
28a80 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  ce code contains
28a90 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
28aa0 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66  entations .** of
28ab0 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
28ac0 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
28ad0 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
28ae0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
28af0 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
28b00 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
28b10 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  me.  The followi
28b20 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ng.** implementa
28b30 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
28b40 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ble in the SQLit
28b50 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e core:.**.** <u
28b60 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
28b70 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a  ITE_MUTEX_OS2.**
28b80 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
28b90 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
28ba0 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
28bb0 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_W32.** <li> 
28bc0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e    SQLITE_MUTEX_N
28bd0 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  OOP.** </ul>.**.
28be0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  ** The SQLITE_MU
28bf0 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
28c00 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
28c10 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a   of routines .**
28c20 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
28c30 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
28c40 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
28c50 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73  r use in .** a s
28c60 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61  ingle-threaded a
28c70 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
28c80 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
28c90 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  2,.** SQLITE_MUT
28ca0 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20  EX_PTHREAD, and 
28cb0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
28cc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28cd0 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69  .** are appropri
28ce0 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f  ate for use on o
28cf0 73 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77  s/2, unix, and w
28d00 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49  indows..** .** I
28d10 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
28d20 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
28d30 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
28d40 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a  F preprocessor.*
28d50 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20  * macro defined 
28d60 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f  (with "-DSQLITE_
28d70 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29  MUTEX_APPDEF=1")
28d80 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a  , then no mutex.
28d90 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
28da0 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69  n is included wi
28db0 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20  th the library. 
28dc0 20 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e   The.** mutex in
28dd0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
28de0 20 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65   defined here be
28df0 63 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a  come external.**
28e00 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74   references in t
28e10 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
28e20 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c  y for which impl
28e30 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d  ementations.** m
28e40 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20  ust be provided 
28e50 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
28e60 6f 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69  on.  This facili
28e70 74 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20  ty allows an.** 
28e80 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
28e90 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53   links against S
28ea0 51 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65  QLite to provide
28eb0 20 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a   its own mutex.*
28ec0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
28ed0 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
28ee0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  to modify the SQ
28ef0 4c 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a  Lite core..**.**
28f00 20 7b 46 31 37 30 31 31 7d 20 54 68 65 20 73 71   {F17011} The sq
28f10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
28f20 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f  c() routine allo
28f30 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d  cates a new.** m
28f40 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73  utex and returns
28f50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
28f60 2e 20 7b 46 31 37 30 31 32 7d 20 49 66 20 69 74  . {F17012} If it
28f70 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a   returns NULL.**
28f80 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74   that means that
28f90 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e   a mutex could n
28fa0 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e  ot be allocated.
28fb0 20 7b 46 31 37 30 31 33 7d 20 53 51 4c 69 74 65   {F17013} SQLite
28fc0 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20  .** will unwind 
28fd0 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65  its stack and re
28fe0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b  turn an error. {
28ff0 46 31 37 30 31 34 7d 20 54 68 65 20 61 72 67 75  F17014} The argu
29000 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
29010 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
29020 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
29030 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
29040 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ts:.**.** <ul>.*
29050 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
29060 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69  UTEX_FAST.** <li
29070 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
29080 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69  RECURSIVE.** <li
29090 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
290a0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a  STATIC_MASTER.**
290b0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
290c0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a  TEX_STATIC_MEM.*
290d0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
290e0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
290f0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
29100 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52  _MUTEX_STATIC_PR
29110 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  NG.** <li>  SQLI
29120 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
29130 4c 52 55 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  LRU.** </ul> {EN
29140 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 35  D}.**.** {F17015
29150 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  } The first two 
29160 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
29170 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
29180 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
29190 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
291a0 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
291b0 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
291c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
291d0 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
291e0 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
291f0 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
29200 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
29210 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a   is used. {END}.
29220 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70  ** The mutex imp
29230 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
29240 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b   not need to mak
29250 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  e a distinction.
29260 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
29270 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
29280 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  E and SQLITE_MUT
29290 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f  EX_FAST if it do
292a0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
292b0 6f 2e 20 20 7b 46 31 37 30 31 36 7d 20 42 75 74  o.  {F17016} But
292c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
292d0 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
292e0 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
292f0 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
29300 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
29310 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66  e.  {END} If a f
29320 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
29330 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
29340 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
29350 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
29360 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
29370 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
29380 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
29390 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
293a0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
293b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
293c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 37 7d  ..**.** {F17017}
293d0 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
293e0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
293f0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
29400 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
29410 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
29420 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
29430 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b  xisting mutex. {
29440 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69  END}  Four stati
29450 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  c mutexes are.**
29460 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72   used by the cur
29470 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  rent version of 
29480 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20  SQLite.  Future 
29490 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
294a0 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64  te.** may add ad
294b0 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
294c0 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63  mutexes.  Static
294d0 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72   mutexes are for
294e0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
294f0 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e   by SQLite only.
29500 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
29510 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  hat use SQLite m
29520 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a  utexes should.**
29530 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79   use only the dy
29540 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65  namic mutexes re
29550 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45  turned by SQLITE
29560 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a  _MUTEX_FAST or.*
29570 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
29580 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20  ECURSIVE..**.** 
29590 7b 46 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68  {F17018} Note th
295a0 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
295b0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
295c0 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
295d0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
295e0 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
295f0 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
29600 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
29610 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
29620 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
29630 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
29640 65 72 79 20 63 61 6c 6c 2e 20 20 7b 46 31 37 30  ery call.  {F170
29650 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20  34} But for the 
29660 73 74 61 74 69 63 20 0a 2a 2a 20 6d 75 74 65 78  static .** mutex
29670 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65   types, the same
29680 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e   mutex is return
29690 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c  ed on every call
296a0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65   that has.** the
296b0 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65   same type numbe
296c0 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  r. {END}.**.** {
296d0 46 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69  F17019} The sqli
296e0 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29  te3_mutex_free()
296f0 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63   routine dealloc
29700 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c  ates a previousl
29710 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64  y.** allocated d
29720 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 46  ynamic mutex. {F
29730 31 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73  17020} SQLite is
29740 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c   careful to deal
29750 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20  locate every.** 
29760 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68  dynamic mutex th
29770 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e  at it allocates.
29780 20 7b 55 31 37 30 32 31 7d 20 54 68 65 20 64 79   {U17021} The dy
29790 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75  namic mutexes mu
297a0 73 74 20 6e 6f 74 20 62 65 20 69 6e 20 0a 2a 2a  st not be in .**
297b0 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61   use when they a
297c0 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20  re deallocated. 
297d0 7b 55 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74  {U17022} Attempt
297e0 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74  ing to deallocat
297f0 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  e a static.** mu
29800 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75  tex results in u
29810 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
29820 72 2e 20 7b 46 31 37 30 32 33 7d 20 53 51 4c 69  r. {F17023} SQLi
29830 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63  te never dealloc
29840 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63  ates.** a static
29850 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a   mutex. {END}.**
29860 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29870 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e  mutex_enter() an
29880 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
29890 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61  try() routines a
298a0 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74  ttempt.** to ent
298b0 65 72 20 61 20 6d 75 74 65 78 2e 20 7b 46 31 37  er a mutex. {F17
298c0 30 32 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20  024} If another 
298d0 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64  thread is alread
298e0 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74  y within the mut
298f0 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ex,.** sqlite3_m
29900 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c  utex_enter() wil
29910 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69  l block and sqli
29920 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
29930 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53  will return.** S
29940 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b 46 31 37  QLITE_BUSY. {F17
29950 30 32 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65  025}  The sqlite
29960 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e  3_mutex_try() in
29970 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29980 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f  SQLITE_OK.** upo
29990 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74  n successful ent
299a0 72 79 2e 20 20 7b 46 31 37 30 32 36 7d 20 4d 75  ry.  {F17026} Mu
299b0 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73  texes created us
299c0 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55  ing.** SQLITE_MU
299d0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61  TEX_RECURSIVE ca
299e0 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c  n be entered mul
299f0 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74  tiple times by t
29a00 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a  he same thread..
29a10 2a 2a 20 7b 46 31 37 30 32 37 7d 20 49 6e 20 73  ** {F17027} In s
29a20 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
29a30 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
29a40 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
29a50 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
29a60 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
29a70 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
29a80 65 72 2e 20 20 7b 55 31 37 30 32 38 7d 20 49 66  er.  {U17028} If
29a90 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
29aa0 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20   tries to enter 
29ab0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e  any other.** kin
29ac0 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20  d of mutex more 
29ad0 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62  than once, the b
29ae0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29af0 69 6e 65 64 2e 0a 2a 2a 20 7b 46 31 37 30 32 39  ined..** {F17029
29b00 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  } SQLite will ne
29b10 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73  ver exhibit.** s
29b20 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20  uch behavior in 
29b30 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d  its own use of m
29b40 75 74 65 78 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a  utexes. {END}.**
29b50 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73  .** Some systems
29b60 20 28 65 78 3a 20 77 69 6e 64 6f 77 73 39 35 29   (ex: windows95)
29b70 20 64 6f 20 6e 6f 74 20 74 68 65 20 6f 70 65 72   do not the oper
29b80 61 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 65  ation implemente
29b90 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d by.** sqlite3_
29ba0 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e  mutex_try().  On
29bb0 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20   those systems, 
29bc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
29bd0 79 28 29 20 77 69 6c 6c 0a 2a 2a 20 61 6c 77 61  y() will.** alwa
29be0 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ys return SQLITE
29bf0 5f 42 55 53 59 2e 20 20 7b 46 31 37 30 33 30 7d  _BUSY.  {F17030}
29c00 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
29c10 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a   only ever uses.
29c20 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
29c30 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74  _try() as an opt
29c40 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69  imization so thi
29c50 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20  s is acceptable 
29c60 62 65 68 61 76 69 6f 72 2e 20 7b 45 4e 44 7d 0a  behavior. {END}.
29c70 2a 2a 0a 2a 2a 20 7b 46 31 37 30 33 31 7d 20 54  **.** {F17031} T
29c80 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
29c90 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
29ca0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
29cb0 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
29cc0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
29cd0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
29ce0 2e 20 20 7b 55 31 37 30 33 32 7d 20 54 68 65 20  .  {U17032} The 
29cf0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
29d00 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
29d10 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
29d20 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
29d30 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
29d40 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
29d50 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
29d60 63 61 74 65 64 2e 20 20 7b 46 31 37 30 33 33 7d  cated.  {F17033}
29d70 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
29d80 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e  never do either.
29d90 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65   {END}.**.** See
29da0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29db0 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e  mutex_held()] an
29dc0 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
29dd0 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a  _notheld()]..*/.
29de0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
29df0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
29e00 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
29e10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
29e20 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
29e30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
29e40 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
29e50 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
29e60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
29e70 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
29e80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29e90 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
29ea0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a  te3_mutex*);../*
29eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
29ec0 74 65 78 20 56 65 72 69 66 63 61 74 69 6f 6e 20  tex Verifcation 
29ed0 52 6f 75 74 69 6e 65 73 20 7b 46 31 37 30 38 30  Routines {F17080
29ee0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
29ef0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
29f00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
29f10 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75  ex_notheld() rou
29f20 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74  tines.** are int
29f30 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
29f40 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74  side assert() st
29f50 61 74 65 6d 65 6e 74 73 2e 20 7b 46 31 37 30 38  atements. {F1708
29f60 31 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  1} The SQLite co
29f70 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73  re.** never uses
29f80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
29f90 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e  except inside an
29fa0 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70   assert() and ap
29fb0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  plications.** ar
29fc0 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c  e advised to fol
29fd0 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20  low the lead of 
29fe0 74 68 65 20 63 6f 72 65 2e 20 20 7b 46 31 37 30  the core.  {F170
29ff0 38 32 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c  82} The core onl
2a000 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d  y.** provides im
2a010 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
2a020 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2a030 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
2a040 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  iled.** with the
2a050 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c   SQLITE_DEBUG fl
2a060 61 67 2e 20 20 7b 55 31 37 30 38 37 7d 20 45 78  ag.  {U17087} Ex
2a070 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70  ternal mutex imp
2a080 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
2a090 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65  are only require
2a0a0 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65  d to provide the
2a0b0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53  se routines if S
2a0c0 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a  QLITE_DEBUG is.*
2a0d0 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66  * defined and if
2a0e0 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64   NDEBUG is not d
2a0f0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  efined..**.** {F
2a100 31 37 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75  17083} These rou
2a110 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74  tines should ret
2a120 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
2a130 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61  mutex in their a
2a140 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65  rgument.** is he
2a150 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20  ld or not held, 
2a160 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79  respectively, by
2a170 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
2a180 65 61 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ead. {END}.**.**
2a190 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d   {X17084} The im
2a1a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
2a1b0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20  not required to 
2a1c0 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e  provided version
2a1d0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f  s of these.** ro
2a1e0 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75  utines that actu
2a1f0 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66  ally work..** If
2a200 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2a210 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f  ion does not pro
2a220 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20  vide working.** 
2a230 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
2a240 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73  e routines, it s
2a250 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70  hould at least p
2a260 72 6f 76 69 64 65 20 73 74 75 62 73 0a 2a 2a 20  rovide stubs.** 
2a270 74 68 61 74 20 61 6c 77 61 79 73 20 72 65 74 75  that always retu
2a280 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20  rn true so that 
2a290 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74  one does not get
2a2a0 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 61 73 73   spurious.** ass
2a2b0 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e  ertion failures.
2a2c0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
2a2d0 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 72 67  7085} If the arg
2a2e0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2a2f0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73  _mutex_held() is
2a300 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2a310 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74  then.** the rout
2a320 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ine should retur
2a330 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73  n 1.  {END} This
2a340 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69   seems counter-i
2a350 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a  ntuitive since.*
2a360 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75  * clearly the mu
2a370 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65  tex cannot be he
2a380 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f  ld if it does no
2a390 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68  t exist.  But th
2a3a0 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20  e.** the reason 
2a3b0 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e  the mutex does n
2a3c0 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61  ot exist is beca
2a3d0 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73  use the build is
2a3e0 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75   not.** using mu
2a3f0 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64  texes.  And we d
2a400 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61  o not want the a
2a410 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69  ssert() containi
2a420 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74  ng the.** call t
2a430 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
2a440 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20  held() to fail, 
2a450 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  so a non-zero re
2a460 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61  turn is.** the a
2a470 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67  ppropriate thing
2a480 20 74 6f 20 64 6f 2e 20 20 7b 46 31 37 30 38 36   to do.  {F17086
2a490 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
2a4a0 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a  tex_notheld() .*
2a4b0 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  * interface shou
2a4c0 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31  ld also return 1
2a4d0 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55   when given a NU
2a4e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69  LL pointer..*/.i
2a4f0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
2a500 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  _held(sqlite3_mu
2a510 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
2a520 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
2a530 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
2a540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a550 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b  F: Mutex Types {
2a560 46 31 37 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F17001}.**.** {F
2a570 31 37 30 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  17002} The [sqli
2a580 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
2a590 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b  )] interface tak
2a5a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
2a5b0 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73  ment.** which is
2a5c0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
2a5d0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e  teger constants.
2a5e0 20 7b 45 4e 44 7d 0a 2a 2f 0a 23 64 65 66 69 6e   {END}.*/.#defin
2a5f0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  e SQLITE_MUTEX_F
2a600 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  AST             
2a610 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2a620 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
2a630 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2a640 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
2a650 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20  TATIC_MASTER    
2a660 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2a670 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
2a680 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71  M       3  /* sq
2a690 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a  lite3_malloc() *
2a6a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2a6b0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
2a6c0 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71  M2      4  /* sq
2a6d0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2a6e0 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e  mory() */.#defin
2a6f0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
2a700 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20  TATIC_PRNG      
2a710 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61  5  /* sqlite3_ra
2a720 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e  ndom() */.#defin
2a730 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
2a740 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20  TATIC_LRU       
2a750 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c  6  /* lru page l
2a760 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ist */../*.** CA
2a770 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65  PI3REF: Low-Leve
2a780 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74  l Control Of Dat
2a790 61 62 61 73 65 20 46 69 6c 65 73 20 7b 46 31 31  abase Files {F11
2a7a0 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  300}.**.** {F113
2a7b0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
2a7c0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
2a7d0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
2a7e0 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74   a direct call t
2a7f0 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f  o the.** xFileCo
2a800 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72  ntrol method for
2a810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
2a820 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
2a830 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
2a840 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
2a850 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69   database identi
2a860 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
2a870 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31  nd argument. {F1
2a880 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d  1302} The.** nam
2a890 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2a8a0 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73  e is the name as
2a8b0 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61  signed to the da
2a8c0 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a  tabase by the.**
2a8d0 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61   <a href="lang_a
2a8e0 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41  ttach.html">ATTA
2a8f0 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61  CH</a> SQL comma
2a900 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74  nd that opened t
2a910 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
2a920 7b 46 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74  {F11303} To cont
2a930 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74  rol the main dat
2a940 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20  abase file, use 
2a950 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a  the name "main".
2a960 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ** or a NULL poi
2a970 6e 74 65 72 2e 20 7b 46 31 31 33 30 34 7d 20 54  nter. {F11304} T
2a980 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2a990 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
2a9a0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  o this routine.*
2a9b0 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72  * are passed dir
2a9c0 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f  ectly through to
2a9d0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
2a9e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73  third parameters
2a9f0 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65   of.** the xFile
2aa00 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
2aa10 20 7b 46 31 31 33 30 35 7d 20 54 68 65 20 72 65   {F11305} The re
2aa20 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2aa30 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a  e xFileControl.*
2aa40 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73  * method becomes
2aa50 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2aa60 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
2aa70 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 36  e..**.** {F11306
2aa80 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  } If the second 
2aa90 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61  parameter (zDbNa
2aaa0 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74  me) does not mat
2aab0 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ch the name of a
2aac0 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ny.** open datab
2aad0 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53  ase file, then S
2aae0 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72  QLITE_ERROR is r
2aaf0 65 74 75 72 6e 65 64 2e 20 7b 46 31 31 33 30 37  eturned. {F11307
2ab00 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20  } This error.** 
2ab10 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65  code is not reme
2ab20 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20  mbered and will 
2ab30 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20  not be recalled 
2ab40 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  by [sqlite3_errc
2ab50 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  ode()].** or [sq
2ab60 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2ab70 20 7b 55 31 31 33 30 38 7d 20 54 68 65 20 75 6e   {U11308} The un
2ab80 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f  derlying xFileCo
2ab90 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67  ntrol method mig
2aba0 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72  ht.** also retur
2abb0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  n SQLITE_ERROR. 
2abc0 20 7b 55 31 31 33 30 39 7d 20 54 68 65 72 65 20   {U11309} There 
2abd0 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73  is no way to dis
2abe0 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e  tinguish between
2abf0 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74  .** an incorrect
2ac00 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20   zDbName and an 
2ac10 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74  SQLITE_ERROR ret
2ac20 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64  urn from the und
2ac30 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65  erlying.** xFile
2ac40 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
2ac50 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20  {END}.**.** See 
2ac60 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43  also: [SQLITE_FC
2ac70 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a  NTL_LOCKSTATE].*
2ac80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2ac90 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74  le_control(sqlit
2aca0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
2acb0 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70  *zDbName, int op
2acc0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
2acd0 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74   Undo the hack t
2ace0 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f  hat converts flo
2acf0 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65  ating point type
2ad00 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72  s to integer for
2ad10 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72  .** builds on pr
2ad20 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74  ocessors without
2ad30 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2ad40 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64  support..*/.#ifd
2ad50 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2ad60 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2ad70 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e  undef double.#en
2ad80 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70  dif..#ifdef __cp
2ad90 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e  lusplus.}  /* En
2ada0 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e  d of the 'extern
2adb0 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23   "C"' block */.#
2adc0 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a           endif.#endif.