/ Hex Artifact Content
Login

Artifact 544587c10005dde0ad8f132dd9b7816b132b2bea:


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 36 20 32 30 30 37 2f  in,v 1.276 2007/
05f0: 31 32 2f 30 36 20 30 32 3a 34 32 3a 30 38 20 64  12/06 02:42:08 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 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
30a0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
30b0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
30c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
30d0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
30e0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
30f0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3110: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3120: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3130: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3140: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3150: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3160: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3170: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3180: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
31a0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
31b0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
31c0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
31d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
31e0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
31f0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
3200: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
3210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
3220: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
3230: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
3240: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
3250: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
3260: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
3270: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
3280: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
3290: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
32a0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
32b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
32c0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
32d0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
32e0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
32f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3300: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
3310: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
3320: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
3330: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
3340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
3350: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
3360: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
3370: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
3380: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
3390: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
33a0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
33b0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
33c0: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
33d0: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
33e0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
33f0: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
3400: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
3410: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
3420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
3430: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
3440: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
3450: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
3460: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
3470: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
3480: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
3490: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
34a0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
34b0: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
34c0: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
34d0: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
34e0: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
34f0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
3500: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
3510: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
3520: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
3530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
3540: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
3550: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
3560: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
3570: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
3580: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
3590: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
35a0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
35b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
35c0: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
35d0: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
35e0: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
35f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
3600: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
3610: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
3620: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
3630: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
3640: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
3650: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
3660: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
3670: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3680: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
3690: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
36a0: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
36b0: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
36c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
36d0: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
36e0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
36f0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
3700: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
3710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
3720: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
3730: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
3740: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
3750: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
3760: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
3770: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
3780: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
3790: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
37a0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
37b0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
37c0: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
37d0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
37e0: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
37f0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
3800: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
3810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
3820: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
3830: 65 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 0a 2a  es {F10220}.**.*
3840: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
3850: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
3860: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
3870: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
3880: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
3890: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
38a0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
38b0: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
38c0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a   has shown that.
38d0: 2a 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65  ** many of these
38e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
38f0: 65 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61  e too course-gra
3900: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
3910: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
3920: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
3930: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
3940: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
3950: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
3960: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
3970: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
3980: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
3990: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
39a0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
39b0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
39c0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
39d0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
39e0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
39f0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
3a00: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
3a10: 65 72 72 6f 72 73 2e 20 7b 46 31 30 32 32 31 7d  errors. {F10221}
3a20: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3a30: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3a40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
3a50: 65 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64  ed.** for each d
3a60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a70: 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  on using the [sq
3a80: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
3a90: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a  esult_codes()].*
3aa0: 2a 20 41 50 49 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  * API. {END}.** 
3ab0: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
3ac0: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
3ad0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3ae0: 61 72 65 20 6c 69 73 74 65 64 20 61 62 6f 76 65  are listed above
3af0: 2e 0a 2a 2a 20 57 65 20 65 78 70 65 63 74 20 74  ..** We expect t
3b00: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
3b10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3b20: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
3b30: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
3b40: 20 7b 55 31 30 34 32 32 7d 20 53 6f 66 74 77 61   {U10422} Softwa
3b50: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74  re that uses ext
3b60: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3b70: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74  es should expect
3b80: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72  .** to see new r
3b90: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66  esult codes in f
3ba0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
3bb0: 66 20 53 51 4c 69 74 65 2e 20 7b 45 4e 44 7d 0a  f SQLite. {END}.
3bc0: 2a 2a 20 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20  ** .** {F10223} 
3bd0: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
3be0: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
3bf0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c  d result code al
3c00: 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  ways contains.**
3c10: 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61   a related prima
3c20: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  ry result code a
3c30: 73 20 61 20 70 72 65 66 69 78 2e 20 7b 46 31 30  s a prefix. {F10
3c40: 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73  224} Primary res
3c50: 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 63 6f 6e  ult.** codes con
3c60: 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f  tain a single "_
3c70: 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 7b 46  " character.  {F
3c80: 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20  10225} Extended 
3c90: 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20  result codes.** 
3ca0: 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d  contain two or m
3cb0: 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  ore "_" characte
3cc0: 72 73 2e 20 7b 46 31 30 32 32 36 7d 20 54 68 65  rs. {F10226} The
3cd0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
3ce0: 66 20 61 6e 0a 2a 2a 20 65 78 74 65 6e 64 65 64  f an.** extended
3cf0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61 6e   result code can
3d00: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
3d10: 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   its.** correspo
3d20: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
3d30: 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61 73  sult code by mas
3d40: 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f 77  king off the low
3d50: 65 72 20 38 20 62 79 74 65 73 2e 20 7b 45 4e 44  er 8 bytes. {END
3d60: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  }.**.** The SQLI
3d70: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
3d80: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
3d90: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
3da0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
3db0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
3dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3dd0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
3de0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3df0: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
3e00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3e10: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28  _SHORT_READ    (
3e20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3e30: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
3e40: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54  QLITE_IOERR_WRIT
3e50: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
3e60: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
3e70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3e80: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
3e90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3ea0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
3eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ec0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
3ed0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3ee0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
3ef0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
3f00: 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c 49  NCATE      (SQLI
3f10: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38  TE_IOERR | (6<<8
3f20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3f30: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20  E_IOERR_FSTAT   
3f40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3f50: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
3f60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3f70: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
3f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3f90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
3fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
3fb0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  LOCK        (SQL
3fc0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
3fd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3fe0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
3ff0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4000: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a  OERR | (10<<8)).
4010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4020: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20  OERR_BLOCKED    
4030: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4040: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
4050: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4060: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 28  _NOMEM         (
4070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4080: 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  12<<8))../*.** C
4090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
40a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
40b0: 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30 7d  rations {F10230}
40c0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 33 31 7d 20  .**.** {F10231} 
40d0: 53 6f 6d 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  Some combination
40e0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 20 62 69   of the these bi
40f0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 75 73 65  t values are use
4100: 64 20 61 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  d as the.** thir
4110: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
4120: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
4130: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
4140: 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75 72 74 68  and.** as fourth
4150: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
4160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
4170: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4180: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
4190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
41a0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
41b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
41c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
41d0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
41e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
41f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4200: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
4210: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
4220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4230: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
4240: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
4250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4260: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
4270: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
4280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4290: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
42a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
42b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
42c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
42d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
42e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
42f0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
4300: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
4310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4320: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
4330: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
4340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4350: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
4360: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
4370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4380: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
4390: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
43a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43b0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
43c0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
43d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
43e0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
43f0: 65 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30  eristics {F10240
4400: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 34 31 7d  }.**.** {F10241}
4410: 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61   The xDeviceCapa
4420: 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20  bilities method 
4430: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
4440: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
4450: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
4460: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
4470: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
4480: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  e these.** bit v
4490: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
44a0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
44b0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
44c0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
44d0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
44e0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
44f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4500: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
4510: 6f 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  o. {END}.**.** {
4520: 46 31 30 32 34 32 7d 20 54 68 65 20 53 51 4c 49  F10242} The SQLI
4530: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
4540: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
4550: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
4560: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
4570: 65 20 61 74 6f 6d 69 63 2e 20 20 7b 46 31 30 32  e atomic.  {F102
4580: 34 33 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 49  43} The SQLITE_I
4590: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
45a0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
45b0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
45c0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
45d0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
45e0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
45f0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
4600: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
4610: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
4620: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
4630: 63 2e 20 20 7b 46 31 30 32 34 34 7d 20 54 68 65  c.  {F10244} The
4640: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
4650: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
4660: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
4670: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
4680: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
4690: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
46a0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
46b0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
46c0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
46d0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
46e0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
46f0: 64 2e 20 20 7b 46 31 30 32 34 35 7d 20 54 68 65  d.  {F10245} The
4700: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
4710: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
4720: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
4730: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
4740: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
4750: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
4760: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
4770: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65  xWrite()..*/.#de
4780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4790: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
47a0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
47b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
47c0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
47d0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
47e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
47f0: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
4800: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
4810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4820: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
4830: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
4840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4850: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
4860: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
4870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4880: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
4890: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
48b0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
48c0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
48d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
48e0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
48f0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
4900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4910: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
4920: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4940: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
4950: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
4960: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4970: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
4980: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a    0x00000400../*
4990: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
49a0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
49b0: 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a  s {F10250}.**.**
49c0: 20 7b 46 31 30 32 35 31 7d 20 53 51 4c 69 74 65   {F10251} SQLite
49d0: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
49e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
49f0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
4a00: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
4a10: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
4a20: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
4a30: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
4a40: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
4a50: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
4a60: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
4a70: 20 7b 45 4e 44 7d 0a 2a 2f 0a 23 64 65 66 69 6e   {END}.*/.#defin
4a80: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
4a90: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
4aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4ab0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
4ac0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
4ad0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
4ae0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
4af0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
4b00: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
4b20: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
4b30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
4b40: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
4b50: 79 70 65 20 46 6c 61 67 73 20 7b 46 31 30 32 36  ype Flags {F1026
4b60: 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 31  0}.**.** {F10261
4b70: 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
4b80: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
4b90: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
4ba0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
4bb0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
4bc0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
4bd0: 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 74 68  ion of the.** th
4be0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
4bf0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
4c00: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
4c10: 20 7b 46 31 30 32 36 32 7d 20 57 68 65 6e 20 74   {F10262} When t
4c20: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
4c30: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
4c40: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
4c50: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
4c60: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
4c70: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
4c80: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
4c90: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
4ca0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
4cb0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 7b  ot be flushed. {
4cc0: 46 31 30 32 36 33 7d 20 54 68 65 20 53 51 4c 49  F10263} The SQLI
4cd0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d  TE_SYNC_NORMAL m
4ce0: 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20  eans .** to use 
4cf0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
4d00: 65 6d 61 6e 74 69 63 73 2e 20 7b 46 31 30 32 36  emantics. {F1026
4d10: 34 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  4} The SQLITE_SY
4d20: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
4d30: 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ns .** to use Ma
4d40: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
4d50: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
4d60: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
4d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4d80: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
4d90: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
4da0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
4db0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
4dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4dd0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
4de0: 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a     0x00010.../*.
4df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
4e00: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
4e10: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31  ile Handle {F111
4e20: 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10}.**.** An [sq
4e30: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
4e40: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
4e50: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
4e60: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
4e70: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
4e80: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
4e90: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
4ea0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
4eb0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
4ec0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
4ed0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
4ee0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
4ef0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
4f00: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
4f10: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
4f20: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
4f30: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
4f40: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
4f50: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
4f60: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
4f70: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
4f80: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
4f90: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
4fa0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
4fb0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
4fc0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
4fd0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
4fe0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
4ff0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
5000: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
5010: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
5020: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
5030: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
5040: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
5050: 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a  Object {F11120}.
5060: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
5070: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
5080: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
5090: 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69  en method contai
50a0: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  ns a pointer to.
50b0: 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** an instance o
50c0: 66 20 74 68 65 20 74 68 69 73 20 6f 62 6a 65 63  f the this objec
50d0: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
50e0: 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d  defines the.** m
50f0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
5100: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
5110: 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73  perations agains
5120: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  t the open file.
5130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
5140: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
5150: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
5160: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
5170: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
5180: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
5190: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
51a0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
51b0: 66 73 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20  fsync()..*  The 
51c0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
51d0: 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c   an.** OS-X styl
51e0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
51f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
5200: 41 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  A flag may be OR
5210: 65 64 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69  ed in to.** indi
5220: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
5230: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
5240: 69 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  ile and not its 
5250: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
5260: 65 0a 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20  e.** synced..** 
5270: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
5280: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
5290: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
52a0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
52b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
52c0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
52d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
52e0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
52f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5300: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
5310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5320: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
5330: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5340: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
5350: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
5360: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
5370: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
5380: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
5390: 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78  lock.  .** The x
53a0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
53b0: 6b 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73  k() method looks
53c0: 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e  .** to see if an
53d0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
53e0: 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e  ction, either in
53f0: 20 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73   this.** process
5400: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
5410: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
5420: 6c 64 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45  lding an RESERVE
5430: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
5440: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
5450: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
5460: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
5470: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
5480: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
5490: 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a  e if not..** .**
54a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
54b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
54c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
54d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
54e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
54f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
5500: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
5510: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
5520: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
5530: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
5540: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
5550: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
5560: 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e  rgument.** is an
5570: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
5580: 20 20 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20     The third.** 
5590: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
55a0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68  neric pointer wh
55b0: 69 63 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ich is intended 
55c0: 74 6f 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a  to be a pointer.
55d0: 2a 2a 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  ** to a structur
55e0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
55f0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
5600: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
5610: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
5620: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
5630: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
5640: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
5650: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
5660: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
5670: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
5680: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
5690: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
56a0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
56b0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
56c0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
56d0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
56e0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
56f0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
5700: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
5710: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
5720: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
5730: 73 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  s opcodes less t
5740: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
5750: 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b  own use. .** A [
5760: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
5770: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
5780: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
5790: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
57a0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
57b0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
57c0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
57d0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
57e0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
57f0: 73 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  s .** greater th
5800: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
5810: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a  conflicts..**.**
5820: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
5830: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
5840: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
5850: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
5860: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
5870: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
5880: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
5890: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
58a0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
58b0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
58c0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
58d0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
58e0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
58f0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
5900: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
5910: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
5920: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
5930: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
5940: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
5950: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
5960: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
5970: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5980: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5990: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
59a0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
59b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
59c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
59d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
59e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
59f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5a00: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5a10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
5a20: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5a40: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
5a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5a80: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
5a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5aa0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
5ab0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
5ac0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
5ad0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
5ae0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5af0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5b00: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5b10: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
5b20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5b30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5b40: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5b50: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5b60: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5b70: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5b80: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5b90: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5ba0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5bb0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5bc0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5bd0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5be0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5bf0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5c00: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5c10: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5c20: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5c30: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5c40: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5c50: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5c60: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5c70: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5c80: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5c90: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5ca0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5cb0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5cc0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5cd0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ce0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5cf0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5d00: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5d10: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
5d20: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
5d30: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
5d40: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
5d50: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5d60: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
5d70: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
5d80: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
5d90: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
5da0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
5db0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
5dc0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
5dd0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
5de0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
5df0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
5e00: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
5e10: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
5e20: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
5e30: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
5e40: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
5e50: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
5e60: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
5e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
5e80: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
5e90: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
5ea0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
5eb0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
5ec0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
5ed0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
5ee0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
5ef0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
5f00: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
5f10: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
5f20: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
5f30: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
5f40: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
5f50: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
5f60: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
5f70: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
5f80: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
5f90: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
5fa0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
5fb0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
5fc0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
5fd0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
5fe0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
5ff0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
6000: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
6010: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
6020: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
6030: 65 73 20 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a  es {F11310}.**.*
6040: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
6050: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
6060: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
6070: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6080: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
6090: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
60a0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 74 6f 20 74   object and to t
60b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
60c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
60d0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
60e0: 7b 46 31 31 33 31 31 7d 20 54 68 65 20 5b 53 51  {F11311} The [SQ
60f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6100: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
6110: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
6120: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
6130: 6f 64 65 20 63 61 73 65 73 20 74 68 65 20 78 46  ode cases the xF
6140: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6150: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
6160: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
6170: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
6180: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
6190: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
61a0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
61b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
61c0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
61d0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
61e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
61f0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
6200: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
6210: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
6220: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
6230: 20 7b 46 31 31 33 31 32 7d 20 54 68 69 73 20 63   {F11312} This c
6240: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
6250: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
6260: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
6270: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
6280: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
6290: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
62a0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
62b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
62c0: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f  TATE        1../
62d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
62e0: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 46 31 37  utex Handle {F17
62f0: 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  110}.**.** The m
6300: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6310: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6320: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6330: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6340: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6350: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
6360: 20 7b 46 31 37 31 31 31 7d 20 54 68 65 20 53 51   {F17111} The SQ
6370: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
6380: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
6390: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
63a0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
63b0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 7b  qlite3_mutex]. {
63c0: 45 4e 44 7d 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  END} It only.** 
63d0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
63e0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
63f0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
6400: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
6410: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
6420: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
6430: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
6440: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
6450: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
6460: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
6470: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6480: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20  nterface Object 
6490: 7b 46 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F11140}.**.** A
64a0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
64b0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
64c0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
64d0: 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53  between the.** S
64e0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
64f0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
6500: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
6510: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
6520: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
6530: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
6540: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
6550: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20   system"..**.** 
6560: 54 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  The iVersion fie
6570: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
6580: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
6590: 67 65 72 20 66 6f 72 20 66 75 74 75 72 65 0a 2a  ger for future.*
65a0: 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
65b0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
65c0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
65d0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
65e0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
65f0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
6600: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
6610: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
6620: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
6630: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
6640: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
6650: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
6660: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
6670: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
6680: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
6690: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
66a0: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
66b0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
66c0: 73 74 65 72 65 64 20 76 66 73 20 6d 6f 64 75 6c  stered vfs modul
66d0: 65 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  es are kept on a
66e0: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
66f0: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
6700: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
6710: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
6720: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
6730: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
6740: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
6750: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
6760: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
6770: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
6780: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6790: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
67a0: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
67b0: 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  s the list..**.*
67c0: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
67d0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
67e0: 65 6c 64 73 20 69 6e 20 74 68 65 20 73 71 6c 69  elds in the sqli
67f0: 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73 74 72 75  te3_vfs .** stru
6800: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
6810: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
6820: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
6830: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
6840: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
6850: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
6860: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
6870: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
6880: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
6890: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
68a0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
68b0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
68c0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
68d0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
68e0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
68f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
6900: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
6910: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
6920: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
6930: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
6940: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
6950: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
6960: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 31 7d 20 53  **.** {F11141} S
6970: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61  QLite will guara
6980: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46  ntee that the zF
6990: 69 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70  ilename string p
69a0: 61 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65  assed to.** xOpe
69b0: 6e 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61  n() is a full pa
69c0: 74 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61  thname as genera
69d0: 74 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68  ted by xFullPath
69e0: 6e 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68  name() and.** th
69f0: 61 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  at the string wi
6a00: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
6a10: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
6a20: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
6a30: 61 6c 6c 65 64 2e 20 20 7b 45 4e 44 7d 20 53 6f  alled.  {END} So
6a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6a50: 6c 65 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20  le] can store a 
6a60: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
6a70: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
6a80: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
6a90: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
6aa0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
6ab0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 32 7d 20  .**.** {F11142} 
6ac0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
6ad0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
6ae0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
6af0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
6b00: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
6b10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
6b20: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
6b30: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
6b40: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
6b50: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
6b60: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
6b70: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
6b80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
6b90: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
6ba0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b  _OPEN_CREATE]. {
6bb0: 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  END}.** If xOpen
6bc0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
6bd0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
6be0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
6bf0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
6c00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
6c10: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
6c20: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
6c30: 73 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 2e  s may be.** set.
6c40: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 33 7d  .** .** {F11143}
6c50: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
6c60: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
6c70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
6c80: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
6c90: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
6ca0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
6cb0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
6cc0: 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  * .** <ul>.** <l
6cd0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
6ce0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
6cf0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6d00: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
6d10: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
6d20: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
6d30: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
6d40: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
6d50: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
6d60: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6d70: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
6d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6d90: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
6da0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
6db0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
6dc0: 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
6dd0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
6de0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
6df0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
6e00: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
6e10: 2a 20 63 68 61 6e 67 65 73 20 74 68 65 20 77 61  * changes the wa
6e20: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
6e30: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
6e40: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
6e50: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
6e60: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
6e70: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
6e80: 72 20 72 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68  r rollback, migh
6e90: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
6ea0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
6eb0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
6ec0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
6ed0: 75 72 6e 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73  urnal are.** als
6ee0: 6f 20 61 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20  o a no-op.  Any 
6ef0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
6f00: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75  the journal retu
6f10: 72 6e 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  rn SQLITE_IOERR.
6f20: 0a 2a 2a 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  .** Or the imple
6f30: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
6f40: 72 65 63 6f 67 6e 69 7a 65 20 74 68 65 20 61 20  recognize the a 
6f50: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
6f60: 6c 6c 0a 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70  ll.** be doing p
6f70: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
6f80: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
6f90: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20  tes in a random 
6fa0: 6f 72 64 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74  order.** and set
6fb0: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
6fc0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
6fd0: 79 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34  y..** .** {F1114
6fe0: 34 7d 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  4} SQLite might 
6ff0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
7000: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7010: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7020: 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a  .** method:.** .
7030: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7040: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
7050: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
7060: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
7070: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
7080: 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  /ul>.** .** {F11
7090: 31 34 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  145} The [SQLITE
70a0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
70b0: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
70c0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
70d0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
70e0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
70f0: 20 20 7b 46 31 31 31 34 36 7d 20 54 68 65 20 5b    {F11146} The [
7100: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
7110: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
7120: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
7130: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a  MP  databases, j
7140: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20  ournals and for 
7150: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a  subjournals. .**
7160: 20 7b 46 31 31 31 34 37 7d 20 54 68 65 20 5b 53   {F11147} The [S
7170: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7180: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  SIVE] flag means
7190: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
71a0: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f   be opened.** fo
71b0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
71c0: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69  ss.  This flag i
71d0: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69  s set for all fi
71e0: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f  les except.** fo
71f0: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
7200: 61 73 65 20 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a  ase file. {END}.
7210: 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 38 7d 20  ** .** {F11148} 
7220: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
7230: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
7240: 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  y is allocated b
7250: 79 20 53 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20  y SQLite .** to 
7260: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
7270: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
7280: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
7290: 20 74 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d   third .** argum
72a0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b  ent to xOpen.  {
72b0: 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20  END}  The xOpen 
72c0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
72d0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
72e0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
72f0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
7300: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a  t fill it in..**
7310: 20 0a 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54 68   .** {F11149} Th
7320: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7330: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
7340: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
7350: 45 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20  ESS_EXISTS] .** 
7360: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
7370: 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66  existance of a f
7380: 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  ile,.** or [SQLI
7390: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
73a0: 49 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20  ITE] to test to 
73b0: 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65  see.** if a file
73c0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
73d0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
73e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
73f0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f  D].** to test to
7400: 20 73 65 65 20 69 66 20 61 20 66 69 6c 65 20 69   see if a file i
7410: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
7420: 62 6c 65 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20  ble.  {END} The 
7430: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a  file can be a .*
7440: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  * directory..** 
7450: 0a 2a 2a 20 7b 46 31 31 31 35 30 7d 20 53 51 4c  .** {F11150} SQL
7460: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
7470: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
7480: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
7490: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f  yte for.** the o
74a0: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f  utput buffers fo
74b0: 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61  r xGetTempname a
74c0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  nd xFullPathname
74d0: 2e 20 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65  . {F11151} The e
74e0: 78 61 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  xact.** size of 
74f0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
7500: 72 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  r is also passed
7510: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
7520: 74 6f 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68  to both .** meth
7530: 6f 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68  ods. {END} If th
7540: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  e output buffer 
7550: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
7560: 75 67 68 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54  ugh, SQLITE_CANT
7570: 4f 50 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  OPEN.** should b
7580: 65 20 72 65 74 75 72 6e 65 64 2e 20 41 73 20 74  e returned. As t
7590: 68 69 73 20 69 73 20 68 61 6e 64 6c 65 64 20 61  his is handled a
75a0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
75b0: 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66  by SQLite,.** vf
75c0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
75d0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
75e0: 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  r to prevent thi
75f0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a  s by setting .**
7600: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
7610: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
7620: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a  rge value..** .*
7630: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
7640: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
7650: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
7660: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
7670: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
7680: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
7690: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
76a0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
76b0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
76c0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
76d0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
76e0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
76f0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
7700: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
7710: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
7720: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
7730: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
7740: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
7750: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
7760: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
7770: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
7780: 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68  ss obtained.  Th
7790: 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65  e.** xSleep() me
77a0: 74 68 6f 64 20 63 61 75 73 65 20 74 68 65 20 63  thod cause the c
77b0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
77c0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
77d0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
77e0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
77f0: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
7800: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
7810: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7820: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
7830: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
7840: 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74  nt date and.** t
7850: 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ime..*/.typedef 
7860: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
7870: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
7880: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
7890: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
78a0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
78b0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
78c0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
78d0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
78e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
78f0: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
7900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
7910: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
7920: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
7930: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
7940: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
7950: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
7960: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
7970: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
7980: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
7990: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
79a0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
79b0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
79c0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
79d0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
79e0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
79f0: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
7a00: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
7a10: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
7a20: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7a30: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
7a40: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
7a50: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
7a60: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
7a70: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
7a80: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
7a90: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7aa0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
7ab0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
7ac0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
7ad0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7ae0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
7af0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54  );.  int (*xGetT
7b00: 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  empname)(sqlite3
7b10: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c  _vfs*, int nOut,
7b20: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
7b30: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
7b40: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
7b50: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
7b60: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
7b70: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
7b80: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
7b90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
7ba0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
7bb0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
7bc0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
7bd0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
7be0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
7bf0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53  ;.  void *(*xDlS
7c00: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
7c10: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
7c20: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20  ar *zSymbol);.  
7c30: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
7c40: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
7c50: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
7c60: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
7c70: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
7c80: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
7c90: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
7ca0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
7cb0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
7cc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
7cd0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
7ce0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
7cf0: 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  /* New fields
7d00: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
7d10: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
7d20: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
7d30: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
7d40: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
7d50: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
7d60: 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ns. */.};../*.**
7d70: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
7d80: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
7d90: 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31   VFS method {F11
7da0: 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  190}.**.** {F111
7db0: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65  91} These intege
7dc0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
7dd0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
7de0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
7df0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
7e00: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
7e10: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
7e20: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
7e30: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65  determine.** the
7e40: 20 6b 69 6e 64 20 6f 66 20 77 68 61 74 20 6b 69   kind of what ki
7e50: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
7e60: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
7e70: 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69  thod is.** looki
7e80: 6e 67 20 66 6f 72 2e 20 20 7b 46 31 31 31 39 32  ng for.  {F11192
7e90: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  } With SQLITE_AC
7ea0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
7eb0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
7ec0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
7ed0: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 66   to see if the f
7ee0: 69 6c 65 20 65 78 69 73 74 73 2e 20 7b 46 31 31  ile exists. {F11
7ef0: 31 39 33 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c  193} With.** SQL
7f00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
7f10: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
7f20: 73 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  s method checks 
7f30: 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 74 68 65  to see.** if the
7f40: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65   file is both re
7f50: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
7f60: 62 6c 65 2e 20 20 7b 46 31 31 31 39 34 7d 20 57  ble.  {F11194} W
7f70: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43  ith.** SQLITE_AC
7f80: 43 45 53 53 5f 52 45 41 44 20 74 68 65 20 78 41  CESS_READ the xA
7f90: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
7fa0: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66  checks to see if
7fb0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
7fc0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
7fd0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
7fe0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
7ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8000: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
8010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
8020: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
8030: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8040: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
8050: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
8060: 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32 30 30  lt Codes {F12200
8070: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d  }.**.** {F12201}
8080: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74   The sqlite3_ext
8090: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
80a0: 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
80b0: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
80c0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
80d0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
80e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
80f0: 65 73 5d 20 66 65 61 74 75 72 65 20 6f 6e 20 61  es] feature on a
8100: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
8110: 6e 65 63 74 69 6f 6e 20 69 66 20 69 74 73 20 32  nection if its 2
8120: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  nd parameter is.
8130: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 20 7a  ** non-zero or z
8140: 65 72 6f 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ero, respectivel
8150: 79 2e 20 7b 46 31 32 32 30 32 7d 0a 2a 2a 20 42  y. {F12202}.** B
8160: 79 20 64 65 66 61 75 6c 74 2c 20 53 51 4c 69 74  y default, SQLit
8170: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
8180: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c  eturn one of onl
8190: 79 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  y 26 integer.** 
81a0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
81b0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 7b 46 31  ult codes].  {F1
81c0: 32 32 30 33 7d 20 57 68 65 6e 20 65 78 74 65 6e  2203} When exten
81d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
81e0: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
81f0: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  by this routine,
8200: 20 74 68 65 20 72 65 70 65 74 6f 69 72 65 20 6f   the repetoire o
8210: 66 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63  f result codes c
8220: 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c 61  an be.** much la
8230: 72 67 65 72 20 61 6e 64 20 63 61 6e 20 28 68 6f  rger and can (ho
8240: 70 65 66 75 6c 6c 79 29 20 70 72 6f 76 69 64 65  pefully) provide
8250: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
8260: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
8270: 6f 75 74 20 74 68 65 20 63 61 75 73 65 20 6f 66  out the cause of
8280: 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
8290: 20 7b 46 31 32 32 30 34 7d 20 54 68 65 20 73 65   {F12204} The se
82a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
82b0: 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65   a boolean value
82c0: 20 74 68 61 74 20 74 75 72 6e 73 20 65 78 74 65   that turns exte
82d0: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
82e0: 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  odes on and off.
82f0: 20 7b 46 31 32 32 30 35 7d 20 45 78 74 65 6e 64   {F12205} Extend
8300: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
8310: 61 72 65 20 6f 66 66 20 62 79 20 64 65 66 61 75  are off by defau
8320: 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61  lt for.** backwa
8330: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
8340: 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76 65 72  y with older ver
8350: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
8360: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
8370: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
8380: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
8390: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
83a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
83b0: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
83c0: 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12220}.**.** {F
83d0: 31 32 32 32 31 7d 20 45 61 63 68 20 65 6e 74 72  12221} Each entr
83e0: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
83f0: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
8400: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
8410: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
8420: 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64  alled the "rowid
8430: 22 2e 20 20 7b 46 31 32 32 32 32 7d 20 54 68 65  ".  {F12222} The
8440: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
8450: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
8460: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
8470: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
8480: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
8490: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
84a0: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
84b0: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
84c0: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
84d0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 7b  lared columns. {
84e0: 46 31 32 32 32 33 7d 20 49 66 0a 2a 2a 20 74 68  F12223} If.** th
84f0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
8500: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54  lumn of type INT
8510: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
8520: 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
8530: 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
8540: 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  an alias for the
8550: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46   rowid..**.** {F
8560: 31 32 32 32 34 7d 20 54 68 69 73 20 72 6f 75 74  12224} This rout
8570: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
8580: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73  rowid of the mos
8590: 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
85a0: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69 6e  essful INSERT in
85b0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
85c0: 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
85d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
85e0: 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66 69 72  shown in the fir
85f0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 7b 46  st argument.  {F
8600: 31 32 32 32 35 7d 20 49 66 20 6e 6f 20 73 75 63  12225} If no suc
8610: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 73 0a  cessful inserts.
8620: 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
8630: 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61  urred on this da
8640: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8650: 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
8660: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ned..**.** {F122
8670: 32 36 7d 20 49 66 20 61 6e 20 49 4e 53 45 52 54  26} If an INSERT
8680: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
8690: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
86a0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a  he rowid of the.
86b0: 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  ** inserted row 
86c0: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
86d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
86e0: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
86f0: 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  er.** is running
8700: 2e 20 20 7b 46 31 32 32 32 37 7d 20 42 75 74 20  .  {F12227} But 
8710: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
8720: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
8730: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
8740: 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
8750: 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ne reverts to th
8760: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
8770: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
8780: 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65  .** trigger fire
8790: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 38  d..**.** {F12228
87a0: 7d 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74  } An INSERT that
87b0: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
87c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
87d0: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
87e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65   successful inse
87f0: 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  rt and does not 
8800: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
8810: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
8820: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 7b  s.** routine.  {
8830: 46 31 32 32 32 39 7d 20 54 68 75 73 20 49 4e 53  F12229} Thus INS
8840: 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
8850: 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
8860: 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
8870: 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
8880: 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
8890: 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
88a0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
88b0: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
88c0: 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
88d0: 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 7b 46  rtion fails.  {F
88e0: 31 32 32 33 31 7d 20 57 68 65 6e 20 49 4e 53 45  12231} When INSE
88f0: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a  RT OR REPLACE .*
8900: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
8910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
8920: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
8930: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
8940: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
8950: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
8960: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
8970: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
8980: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
8990: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
89a0: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
89b0: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
89c0: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
89d0: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
89e0: 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 7b 55  rface. .**.** {U
89f0: 46 31 32 32 33 32 7d 20 49 66 20 61 6e 6f 74 68  F12232} If anoth
8a00: 65 72 20 74 68 72 65 61 64 20 64 6f 65 73 20 61  er thread does a
8a10: 20 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74   new insert on t
8a20: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
8a30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
8a40: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
8a50: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  e is running and
8a60: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
8a70: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
8a80: 77 69 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  wid,.** then the
8a90: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
8aa0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
8ab0: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73   undefined..*/.s
8ac0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
8ad0: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
8ae0: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
8af0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8b00: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
8b10: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
8b20: 66 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a  fied {F12240}.**
8b30: 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 69  .** {F12241} Thi
8b40: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
8b50: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
8b60: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
8b70: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
8b80: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
8b90: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
8ba0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
8bb0: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
8bc0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
8bd0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
8be0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
8bf0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 7b  rst parameter. {
8c00: 46 31 32 32 34 32 7d 20 4f 6e 6c 79 0a 2a 2a 20  F12242} Only.** 
8c10: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
8c20: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
8c30: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52  ied by the INSER
8c40: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a  T, UPDATE, or.**
8c50: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
8c60: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
8c70: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
8c80: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
8c90: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
8ca0: 63 6f 75 6e 74 65 64 2e 20 7b 46 31 32 32 34 33  counted. {F12243
8cb0: 7d 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  } Use the [sqlit
8cc0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
8cd0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
8ce0: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
8cf0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
8d00: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
8d10: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
8d20: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
8d30: 7b 46 31 32 32 34 34 7d 20 57 69 74 68 69 6e 20  {F12244} Within 
8d40: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
8d50: 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74  igger, the sqlit
8d60: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
8d70: 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e 20 62 65  erface.** can be
8d80: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
8d90: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
8da0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
8db0: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
8dc0: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
8dd0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
8de0: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
8df0: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
8e00: 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
8e10: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34  er..**.** {F1224
8e20: 35 7d 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61  5} All changes a
8e30: 72 65 20 63 6f 75 6e 74 65 64 2c 20 65 76 65 6e  re counted, even
8e40: 20 69 66 20 74 68 65 79 20 61 72 65 20 6c 61 74   if they are lat
8e50: 65 72 20 75 6e 64 6f 6e 65 20 62 79 20 61 0a 2a  er undone by a.*
8e60: 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42  * ROLLBACK or AB
8e70: 4f 52 54 2e 20 20 7b 46 31 32 32 34 36 7d 20 45  ORT.  {F12246} E
8e80: 78 63 65 70 74 2c 20 63 68 61 6e 67 65 73 20 61  xcept, changes a
8e90: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63  ssociated with c
8ea0: 72 65 61 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64  reating and.** d
8eb0: 72 6f 70 70 69 6e 67 20 74 61 62 6c 65 73 20 61  ropping tables a
8ec0: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
8ed0: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 37 7d 20 49  **.** {F12247} I
8ee0: 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  f a callback inv
8ef0: 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  okes [sqlite3_ex
8f00: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
8f10: 33 5f 73 74 65 70 28 29 5d 0a 2a 2a 20 72 65 63  3_step()].** rec
8f20: 75 72 73 69 76 65 6c 79 2c 20 74 68 65 6e 20 74  ursively, then t
8f30: 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  he changes in th
8f40: 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72 73 69  e inner, recursi
8f50: 76 65 20 63 61 6c 6c 20 61 72 65 0a 2a 2a 20 63  ve call are.** c
8f60: 6f 75 6e 74 65 64 20 74 6f 67 65 74 68 65 72 20  ounted together 
8f70: 77 69 74 68 20 74 68 65 20 63 68 61 6e 67 65 73  with the changes
8f80: 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20 63 61   in the outer ca
8f90: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34  ll..**.** {F1224
8fa0: 38 7d 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  8} SQLite implem
8fb0: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
8fc0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
8fd0: 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ble" without.** 
8fe0: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 62  a WHERE clause b
8ff0: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
9000: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
9010: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
9020: 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68  uch.** faster th
9030: 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 67 68  an going through
9040: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
9050: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
9060: 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 61  s from the.** ta
9070: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
9080: 66 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74  f this optimizat
9090: 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20  ion, the change 
90a0: 63 6f 75 6e 74 20 66 6f 72 20 0a 2a 2a 20 22 44  count for .** "D
90b0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
90c0: 22 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 20 72  " will be zero r
90d0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
90e0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
90f0: 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 72 65  nts.** that were
9100: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
9110: 68 65 20 74 61 62 6c 65 2e 20 7b 46 31 32 32 35  he table. {F1225
9120: 31 7d 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  1} To get an acc
9130: 75 72 61 74 65 20 63 6f 75 6e 74 0a 2a 2a 20 6f  urate count.** o
9140: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
9150: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
9160: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
9170: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
9180: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
9190: 7b 55 46 31 32 32 35 32 7d 20 49 66 20 61 6e 6f  {UF12252} If ano
91a0: 74 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65  ther thread make
91b0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
91c0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
91d0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
91e0: 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
91f0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
9200: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
9210: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
9220: 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
9230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
9240: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
9250: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
9260: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
9270: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
9280: 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a  ed {F12260}.***.
9290: 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 69 73  ** {F12261} This
92a0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
92b0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
92c0: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
92d0: 61 74 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  at have been.** 
92e0: 6d 6f 64 69 66 69 65 64 20 62 79 20 49 4e 53 45  modified by INSE
92f0: 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
9300: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
9310: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
9320: 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73  se handle.** was
9330: 20 6f 70 65 6e 65 64 2e 20 7b 46 31 32 32 36 32   opened. {F12262
9340: 7d 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c  } The count incl
9350: 75 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53  udes UPDATE, INS
9360: 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ERT and DELETE .
9370: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 65 78  ** statements ex
9380: 65 63 75 74 65 64 20 61 73 20 70 61 72 74 20 6f  ecuted as part o
9390: 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
93a0: 6d 73 2e 20 20 7b 46 31 32 32 36 33 7d 20 41 6c  ms.  {F12263} Al
93b0: 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65  l changes.** are
93c0: 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e   counted as soon
93d0: 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
93e0: 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
93f0: 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a  m is completed .
9400: 2a 2a 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ** (when the sta
9410: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
9420: 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
9430: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
9440: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
9450: 61 6c 69 7a 65 28 29 5d 29 2e 20 7b 45 4e 44 7d  alize()]). {END}
9460: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
9470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
9480: 6e 67 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  nge()] interface
9490: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 35 7d  ..**.** {F12265}
94a0: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
94b0: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
94c0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
94d0: 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  e" without.** a 
94e0: 57 48 45 52 45 20 63 6c 61 75 73 65 20 62 79 20  WHERE clause by 
94f0: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
9500: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
9510: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
9520: 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e  h.** faster than
9530: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
9540: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
9550: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
9560: 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c  ts form the tabl
9570: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a  e.)  Because of.
9580: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  ** this optimiza
9590: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65  tion, the change
95a0: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45   count for "DELE
95b0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
95c0: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72  ill be.** zero r
95d0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
95e0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
95f0: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
9600: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
9610: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74  ** table. To get
9620: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
9630: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
9640: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
9650: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
9660: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
9670: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
9680: 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66 20  .** {U12264} If 
9690: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d  another thread m
96a0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
96b0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
96c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
96d0: 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
96e0: 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ne is running th
96f0: 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
9700: 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
9710: 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ine.** is undefi
9720: 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e  ned. {END}.*/.in
9730: 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
9740: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
9750: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
9760: 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
9770: 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
9780: 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a  ry {F12270}.**.*
9790: 2a 20 7b 46 31 32 32 37 31 7d 20 54 68 69 73 20  * {F12271} This 
97a0: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
97b0: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
97c0: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
97d0: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
97e0: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
97f0: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
9800: 79 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 72 6f  y. {END} This ro
9810: 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
9820: 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
9830: 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
9840: 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
9850: 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
9860: 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
9870: 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
9880: 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
9890: 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
98a0: 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
98b0: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ely..**.** {F122
98c0: 37 32 7d 20 49 74 20 69 73 20 73 61 66 65 20 74  72} It is safe t
98d0: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
98e0: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
98f0: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
9900: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
9910: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
9920: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
9930: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
9940: 20 7b 55 31 32 32 37 33 7d 20 42 75 74 20 69 74   {U12273} But it
9950: 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
9960: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
9970: 74 69 6e 65 20 77 69 74 68 20 61 20 64 61 74 61  tine with a data
9980: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
9990: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
99a0: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
99b0: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
99c0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
99d0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
99e0: 20 53 51 4c 20 69 73 20 76 65 72 79 20 6e 65 61   SQL is very nea
99f0: 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
9a00: 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 73 71  the time when sq
9a10: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
9a20: 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20  ).** is called, 
9a30: 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
9a40: 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
9a50: 75 6e 69 74 79 20 74 6f 20 62 65 20 69 6e 74 65  unity to be inte
9a60: 72 72 75 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d  rrupted..** It m
9a70: 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
9a80: 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20   completion..** 
9a90: 7b 46 31 32 32 37 34 7d 20 54 68 65 20 53 51 4c  {F12274} The SQL
9aa0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
9ab0: 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
9ac0: 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
9ad0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
9ae0: 2e 20 20 7b 46 31 32 32 37 35 7d 20 49 66 20 74  .  {F12275} If t
9af0: 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
9b00: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
9b10: 61 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20 55 50  an.** INSERT, UP
9b20: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
9b30: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
9b40: 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
9b50: 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65 6e  action, .** then
9b60: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
9b70: 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  saction will be 
9b80: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
9b90: 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20 7b 46  matically..** {F
9ba0: 31 32 32 37 36 7d 20 41 20 63 61 6c 6c 20 74 6f  12276} A call to
9bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
9bc0: 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65  pt() has no effe
9bd0: 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
9be0: 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
9bf0: 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 73   started after s
9c00: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
9c10: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  () returns..*/.v
9c20: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
9c30: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
9c40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9c50: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
9c60: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
9c70: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30  Is Complete {F10
9c80: 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  510}.**.** These
9c90: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
9ca0: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
9cb0: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
9cc0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
9cd0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
9ce0: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
9cf0: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
9d00: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
9d10: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
9d20: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
9d30: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
9d40: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
9d50: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
9d60: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
9d70: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
9d80: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
9d90: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
9da0: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
9db0: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
9dc0: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
9dd0: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
9de0: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
9df0: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
9e00: 65 6d 69 63 6f 6c 6f 6e 20 61 6e 64 20 69 73 20  emicolon and is 
9e10: 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f  not a fragment o
9e20: 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52  f a.** CREATE TR
9e30: 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
9e40: 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
9e50: 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
9e60: 65 20 53 51 4c 20 61 6e 64 0a 2a 2a 20 73 6f 20  e SQL and.** so 
9e70: 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
9e80: 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
9e90: 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
9ea0: 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 73  ** {F10511} Thes
9eb0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
9ec0: 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 67  rn true if the g
9ed0: 69 76 65 6e 20 69 6e 70 75 74 20 73 74 72 69 6e  iven input strin
9ee0: 67 20 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  g .** ends with 
9ef0: 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 6f 70 74 69  a semicolon opti
9f00: 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20  onally followed 
9f10: 62 79 20 77 68 69 74 65 73 70 61 63 65 20 6f 72  by whitespace or
9f20: 0a 2a 2a 20 63 6f 6d 6d 65 6e 74 73 2e 20 7b 46  .** comments. {F
9f30: 31 30 35 31 32 7d 20 46 6f 72 20 73 71 6c 69 74  10512} For sqlit
9f40: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 2c 0a 2a  e3_complete(),.*
9f50: 2a 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  * the parameter 
9f60: 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
9f70: 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
9f80: 73 74 72 69 6e 67 2e 20 7b 46 31 30 35 31 33 7d  string. {F10513}
9f90: 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   For.** sqlite3_
9fa0: 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c 20 61 20  complete16(), a 
9fb0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
9fc0: 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f 72 64  machine byte ord
9fd0: 65 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  er UTF-16 string
9fe0: 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65 64 2e  .** is required.
9ff0: 20 20 7b 46 31 30 35 31 34 7d 20 54 68 65 73 65    {F10514} These
a000: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
a010: 20 66 61 6c 73 65 20 69 66 20 74 68 65 20 74 65   false if the te
a020: 72 6d 69 6e 61 6c 0a 2a 2a 20 73 65 6d 69 63 6f  rminal.** semico
a030: 6c 6f 6e 20 69 73 20 77 69 74 68 69 6e 20 61 20  lon is within a 
a040: 63 6f 6d 6d 65 6e 74 2c 20 61 20 73 74 72 69 6e  comment, a strin
a050: 67 20 6c 69 74 65 72 61 6c 20 6f 72 20 61 20 71  g literal or a q
a060: 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
a070: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
a080: 72 64 73 20 69 66 20 74 68 65 20 66 69 6e 61 6c  rds if the final
a090: 20 73 65 6d 69 63 6f 6c 6f 6e 20 69 73 20 6e 6f   semicolon is no
a0a0: 74 20 72 65 61 6c 6c 79 20 61 20 73 65 70 61 72  t really a separ
a0b0: 61 74 65 20 74 6f 6b 65 6e 0a 2a 2a 20 62 75 74  ate token.** but
a0c0: 20 70 61 72 74 20 6f 66 20 61 20 6c 61 72 67 65   part of a large
a0d0: 72 20 74 6f 6b 65 6e 29 20 6f 72 20 69 66 20 74  r token) or if t
a0e0: 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
a0f0: 6f 6e 20 69 73 0a 2a 2a 20 69 6e 20 62 65 74 77  on is.** in betw
a100: 65 65 6e 20 74 68 65 20 42 45 47 49 4e 20 61 6e  een the BEGIN an
a110: 64 20 45 4e 44 20 6b 65 79 77 6f 72 64 73 20 6f  d END keywords o
a120: 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47  f a CREATE TRIGG
a130: 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  ER statement..**
a140: 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71   {END}.*/.int sq
a150: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
a160: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
a170: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
a180: 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
a190: 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
a1a0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
a1b0: 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
a1c0: 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
a1d0: 42 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32  BUSY Errors {F12
a1e0: 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  310}.**.** {F123
a1f0: 31 31 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  11} This routine
a200: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61   identifies a ca
a210: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
a220: 74 68 61 74 20 6d 69 67 68 74 20 62 65 0a 2a 2a  that might be.**
a230: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
a240: 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  r an attempt is 
a250: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
a260: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a  atabase table .*
a270: 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  * that another t
a280: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
a290: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20   has locked..** 
a2a0: 7b 46 31 32 33 31 32 7d 20 49 66 20 74 68 65 20  {F12312} If the 
a2b0: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
a2c0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
a2d0: 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
a2e0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
a2f0: 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
a300: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
a310: 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
a320: 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ing the lock..**
a330: 20 7b 46 31 32 33 31 33 7d 20 49 66 20 74 68 65   {F12313} If the
a340: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
a350: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
a360: 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b   the.** callback
a370: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
a380: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
a390: 6e 74 73 2e 20 20 7b 46 31 32 33 31 34 7d 20 54  nts.  {F12314} T
a3a0: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
a3b0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
a3c0: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
a3d0: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
a3e0: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
a3f0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
a400: 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  t to this routin
a410: 65 2e 20 20 7b 46 31 32 33 31 35 7d 20 54 68 65  e.  {F12315} The
a420: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
a430: 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
a440: 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
a450: 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
a460: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
a470: 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
a480: 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
a490: 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 7b 46 31  king event.  {F1
a4a0: 32 33 31 36 7d 20 49 66 20 74 68 65 0a 2a 2a 20  2316} If the.** 
a4b0: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
a4c0: 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
a4d0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
a4e0: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
a4f0: 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
a500: 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
a510: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
a520: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
a530: 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
a540: 0a 2a 2a 20 7b 46 31 32 33 31 37 7d 20 49 66 20  .** {F12317} If 
a550: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
a560: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
a570: 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
a580: 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
a590: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
a5a0: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
a5b0: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
a5c0: 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
a5d0: 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
a5e0: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
a5f0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
a600: 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62  hat.** it will b
a610: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  e invoked when t
a620: 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
a630: 74 65 6e 74 69 6f 6e 2e 20 7b 46 31 32 33 31 39  tention. {F12319
a640: 7d 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64  }.** If SQLite d
a650: 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
a660: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
a670: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
a680: 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65  esult in.** a de
a690: 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
a6a0: 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
a6b0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
a6c0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
a6d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
a6e0: 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
a6f0: 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ng the.** busy h
a700: 61 6e 64 6c 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a  andler. {END}.**
a710: 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
a720: 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
a730: 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
a740: 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
a750: 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
a760: 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
a770: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
a780: 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
a790: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
a7a0: 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
a7b0: 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
a7c0: 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
a7d0: 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
a7e0: 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
a7f0: 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
a800: 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
a810: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
a820: 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
a830: 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
a840: 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
a850: 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
a860: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
a870: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
a880: 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
a890: 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
a8a0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
a8b0: 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
a8c0: 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
a8d0: 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
a8e0: 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
a8f0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
a900: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
a910: 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
a920: 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
a930: 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
a940: 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
a950: 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
a960: 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
a970: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
a980: 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
a990: 7b 46 31 32 33 32 31 7d 20 54 68 65 20 64 65 66  {F12321} The def
a9a0: 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
a9b0: 63 6b 20 69 73 20 4e 55 4c 4c 2e 20 7b 45 4e 44  ck is NULL. {END
a9c0: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 32 32 7d  }.**.** {F12322}
a9d0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53   The [SQLITE_BUS
a9e0: 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
a9f0: 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
aa00: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
aa10: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
aa20: 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
aa30: 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
aa40: 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
aa50: 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
aa60: 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
aa70: 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
aa80: 63 61 63 68 65 2e 20 20 7b 46 31 32 33 32 33 7d  cache.  {F12323}
aa90: 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
aaa0: 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
aab0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
aac0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
aad0: 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
aae0: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
aaf0: 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
ab00: 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
ab10: 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
ab20: 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
ab30: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ab40: 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
ab50: 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
ab60: 61 64 65 72 73 2e 20 20 7b 46 31 32 33 32 34 7d  aders.  {F12324}
ab70: 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65   If it is unable
ab80: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
ab90: 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
aba0: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
abb0: 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
abc0: 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
abd0: 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
abe0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
abf0: 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
ac00: 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
ac10: 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
ac20: 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
ac30: 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
ac40: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
ac50: 44 5d 2e 20 20 7b 46 31 32 33 32 35 7d 20 54 68  D].  {F12325} Th
ac60: 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
ac70: 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
ac80: 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
ac90: 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
aca0: 68 61 6e 67 65 73 2e 20 7b 45 4e 44 7d 20 53 65  hanges. {END} Se
acb0: 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
acc0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  ="http://www.sql
acd0: 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f  ite.org/cvstrac/
ace0: 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
acf0: 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
ad00: 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
ad10: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
ad20: 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
ad30: 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
ad40: 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
ad50: 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
ad60: 2e 0a 2a 2a 09 0a 2a 2a 20 7b 46 31 32 33 32 36  ..**..** {F12326
ad70: 7d 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d 65  } Sqlite is re-e
ad80: 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20 62  ntrant, so the b
ad90: 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  usy handler may 
ada0: 73 74 61 72 74 20 61 20 6e 65 77 0a 2a 2a 20 71  start a new.** q
adb0: 75 65 72 79 2e 20 7b 45 4e 44 7d 20 28 49 74 20  uery. {END} (It 
adc0: 69 73 20 6e 6f 74 20 63 6c 65 61 72 20 77 68 79  is not clear why
add0: 20 61 6e 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76   anyone would ev
ade0: 65 72 79 20 77 61 6e 74 20 74 6f 20 64 6f 20 74  ery want to do t
adf0: 68 69 73 2c 0a 2a 2a 20 62 75 74 20 69 74 20 69  his,.** but it i
ae00: 73 20 61 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68  s allowed, in th
ae10: 65 6f 72 79 2e 29 20 7b 55 31 32 33 32 37 7d 20  eory.) {U12327} 
ae20: 42 75 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  But the busy han
ae30: 64 6c 65 72 20 6d 61 79 20 6e 6f 74 0a 2a 2a 20  dler may not.** 
ae40: 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
ae50: 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74 68 65  se.  Closing the
ae60: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 61   database from a
ae70: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69   busy handler wi
ae80: 6c 6c 20 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61  ll delete .** da
ae90: 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 75  ta structures ou
aea0: 74 20 66 72 6f 6d 20 75 6e 64 65 72 20 74 68 65  t from under the
aeb0: 20 65 78 65 63 75 74 69 6e 67 20 71 75 65 72 79   executing query
aec0: 20 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72   and will .** pr
aed0: 6f 62 61 62 6c 79 20 72 65 73 75 6c 74 20 69 6e  obably result in
aee0: 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
aef0: 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 72  fault or other r
af00: 75 6e 74 69 6d 65 20 65 72 72 6f 72 2e 20 7b 45  untime error. {E
af10: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 32  ND}.**.** {F1232
af20: 38 7d 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  8} There can onl
af30: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
af40: 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
af50: 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ed for each data
af60: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
af70: 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  on.  Setting a n
af80: 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
af90: 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69  clears any previ
afa0: 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 7b 46 31  ous one. .** {F1
afb0: 32 33 32 39 7d 20 4e 6f 74 65 20 74 68 61 74 20  2329} Note that 
afc0: 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
afd0: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
afe0: 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
aff0: 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62  r clear.** the b
b000: 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
b010: 2a 2a 20 7b 46 31 32 33 33 31 7d 20 57 68 65 6e  ** {F12331} When
b020: 20 6f 70 65 72 61 74 69 6e 67 20 69 6e 20 5b 73   operating in [s
b030: 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
b040: 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68 61  ared_cache | sha
b050: 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
b060: 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c  .** only a singl
b070: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
b080: 61 6e 20 62 65 20 64 65 66 69 6e 65 64 20 66 6f  an be defined fo
b090: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  r each database 
b0a0: 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66 20 74  file..** So if t
b0b0: 77 6f 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  wo database conn
b0c0: 65 63 74 69 6f 6e 73 20 73 68 61 72 65 20 61 20  ections share a 
b0d0: 73 69 6e 67 6c 65 20 63 61 63 68 65 2c 20 74 68  single cache, th
b0e0: 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a 20 74  en changing.** t
b0f0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
b100: 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f  on one connectio
b110: 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68 61 6e  n will also chan
b120: 67 65 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ge the busy.** h
b130: 61 6e 64 6c 65 72 20 69 6e 20 74 68 65 20 6f 74  andler in the ot
b140: 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  her connection. 
b150: 20 7b 46 31 32 33 33 32 7d 20 54 68 65 20 62 75   {F12332} The bu
b160: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e  sy handler is in
b170: 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20  voked.** in the 
b180: 74 68 72 65 61 64 20 74 68 61 74 20 77 61 73 20  thread that was 
b190: 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20 74 68 65  running when the
b1a0: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
b1b0: 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 69 6e 74 20   occurs..*/.int 
b1c0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
b1d0: 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
b1e0: 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
b1f0: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
b200: 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
b210: 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 46   Busy Timeout {F
b220: 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12340}.**.** {F1
b230: 32 33 34 31 7d 20 54 68 69 73 20 72 6f 75 74 69  2341} This routi
b240: 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
b250: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
b260: 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 0a  | busy handler].
b270: 2a 2a 20 74 68 61 74 20 73 6c 65 65 70 73 20 66  ** that sleeps f
b280: 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20  or a while when 
b290: 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f  a.** table is lo
b2a0: 63 6b 65 64 2e 20 20 7b 46 31 32 33 34 32 7d 20  cked.  {F12342} 
b2b0: 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c  The handler will
b2c0: 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
b2d0: 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20  times until .** 
b2e0: 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
b2f0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
b300: 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e  eeping have been
b310: 20 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20   done. {F12343} 
b320: 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69  After.** "ms" mi
b330: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
b340: 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64  eeping, the hand
b350: 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
b360: 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73  ich.** causes [s
b370: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
b380: 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  o return [SQLITE
b390: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
b3a0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
b3b0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d  ..**.** {F12344}
b3c0: 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
b3d0: 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
b3e0: 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
b3f0: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
b400: 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
b410: 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
b420: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 35 7d  ..**.** {F12345}
b430: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
b440: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
b450: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
b460: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
b470: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
b480: 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
b490: 73 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64  sy handler was d
b4a0: 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69  efined  .** (usi
b4b0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
b4c0: 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
b4d0: 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
b4e0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
b4f0: 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
b500: 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
b510: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
b520: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
b530: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
b540: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
b550: 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
b560: 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
b570: 69 6e 67 20 51 75 65 72 69 65 73 20 7b 46 31 32  ing Queries {F12
b580: 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  370}.**.** This 
b590: 6e 65 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20  next routine is 
b5a0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
b5b0: 61 70 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71  apper around [sq
b5c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a  lite3_exec()]..*
b5d0: 2a 20 7b 46 31 32 33 37 31 7d 20 49 6e 73 74 65  * {F12371} Inste
b5e0: 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61  ad of invoking a
b5f0: 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 63   user-supplied c
b600: 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61 63 68  allback for each
b610: 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72   row of the.** r
b620: 65 73 75 6c 74 2c 20 74 68 69 73 20 72 6f 75 74  esult, this rout
b630: 69 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 65 61  ine remembers ea
b640: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  ch row of the re
b650: 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  sult in memory.*
b660: 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
b670: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b680: 29 5d 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 73  )], then returns
b690: 20 61 6c 6c 20 6f 66 20 74 68 65 20 72 65 73 75   all of the resu
b6a0: 6c 74 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  lt after the.** 
b6b0: 71 75 65 72 79 20 68 61 73 20 66 69 6e 69 73 68  query has finish
b6c0: 65 64 2e 20 7b 46 31 32 33 37 32 7d 0a 2a 2a 0a  ed. {F12372}.**.
b6d0: 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
b6e0: 2c 20 73 75 70 70 6f 73 65 20 74 68 65 20 71 75  , suppose the qu
b6f0: 65 72 79 20 72 65 73 75 6c 74 20 77 68 65 72 65  ery result where
b700: 20 74 68 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a   this table:.**.
b710: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
b720: 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
b730: 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
b740: 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
b750: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
b760: 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
b770: 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
b780: 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
b790: 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
b7a0: 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
b7b0: 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
b7c0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
b7d0: 20 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75   If the 3rd argu
b7e0: 6d 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73  ment were &azRes
b7f0: 75 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74  ult then after t
b800: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
b810: 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20  rns.** azResult 
b820: 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65  will contain the
b830: 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a   following data:
b840: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
b850: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
b860: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
b870: 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
b880: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
b890: 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
b8a0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
b8b0: 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
b8c0: 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
b8d0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
b8e0: 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
b8f0: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
b900: 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
b910: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
b920: 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
b930: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
b940: 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
b950: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
b960: 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
b970: 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
b980: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
b990: 4e 6f 74 69 63 65 20 74 68 61 74 20 74 68 65 72  Notice that ther
b9a0: 65 20 69 73 20 61 6e 20 65 78 74 72 61 20 72 6f  e is an extra ro
b9b0: 77 20 6f 66 20 64 61 74 61 20 63 6f 6e 74 61 69  w of data contai
b9c0: 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e 0a  ning the column.
b9d0: 2a 2a 20 68 65 61 64 65 72 73 2e 20 20 42 75 74  ** headers.  But
b9e0: 20 74 68 65 20 2a 6e 72 6f 77 20 72 65 74 75 72   the *nrow retur
b9f0: 6e 20 76 61 6c 75 65 20 69 73 20 73 74 69 6c 6c  n value is still
ba00: 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73   3.  *ncolumn is
ba10: 0a 2a 2a 20 73 65 74 20 74 6f 20 32 2e 20 20 49  .** set to 2.  I
ba20: 6e 20 67 65 6e 65 72 61 6c 2c 20 74 68 65 20 6e  n general, the n
ba30: 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
ba40: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 61 7a  inserted into az
ba50: 52 65 73 75 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62  Result.** will b
ba60: 65 20 28 28 2a 6e 72 6f 77 29 20 2b 20 31 29 2a  e ((*nrow) + 1)*
ba70: 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a  (*ncolumn)..**.*
ba80: 2a 20 7b 55 31 32 33 37 34 7d 20 41 66 74 65 72  * {U12374} After
ba90: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
baa0: 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
bab0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
bac0: 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a  ult, it should .
bad0: 2a 2a 20 70 61 73 73 20 74 68 65 20 72 65 73 75  ** pass the resu
bae0: 6c 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  lt data pointer 
baf0: 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
bb00: 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
bb10: 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20   to .** release 
bb20: 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
bb30: 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20  was malloc-ed.  
bb40: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
bb50: 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ay the .** [sqli
bb60: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
bb70: 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c 69  ppens, the calli
bb80: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
bb90: 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
bba0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72   .** [sqlite3_fr
bbb0: 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
bbc0: 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f 66   Only [sqlite3_f
bbd0: 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
bbe0: 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
bbf0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  .** the memory p
bc00: 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
bc10: 6c 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ly. {END}.**.** 
bc20: 7b 46 31 32 33 37 33 7d 20 54 68 65 20 72 65 74  {F12373} The ret
bc30: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
bc40: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  s routine is the
bc50: 20 73 61 6d 65 20 61 73 0a 2a 2a 20 66 72 6f 6d   same as.** from
bc60: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
bc70: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
bc80: 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
bc90: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
bca0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
bcb0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
bcc0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
bcd0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
bce0: 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20  be executed */. 
bcf0: 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70   char ***resultp
bd00: 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c  ,       /* Resul
bd10: 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63  t written to a c
bd20: 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68  har *[]  that th
bd30: 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a  is points to */.
bd40: 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20    int *nrow,    
bd50: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
bd60: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
bd70: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
bd80: 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e  /.  int *ncolumn
bd90: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  ,          /* Nu
bda0: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
bdb0: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
bdc0: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
bdd0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
bde0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
bdf0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
be00: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
be10: 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
be20: 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
be30: 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
be40: 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
be50: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  ng Functions {F1
be60: 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  7400}.**.** Thes
be70: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
be80: 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  orkalikes of the
be90: 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
bea0: 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
beb0: 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
bec0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
bed0: 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 31 7d 20 54  **.** {F17401} T
bee0: 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
bef0: 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
bf00: 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
bf10: 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
bf20: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
bf30: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
bf40: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
bf50: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 55 31  alloc()]..** {U1
bf60: 37 34 30 32 7d 20 54 68 65 20 73 74 72 69 6e 67  7402} The string
bf70: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
bf80: 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
bf90: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
bfa0: 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
bfb0: 65 33 5f 66 72 65 65 28 29 5d 2e 20 7b 46 31 37  e3_free()]. {F17
bfc0: 34 30 33 7d 20 20 42 6f 74 68 20 72 6f 75 74 69  403}  Both routi
bfd0: 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
bfe0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
bff0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c000: 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
c010: 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
c020: 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
c030: 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
c040: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
c050: 31 37 34 30 34 7d 20 49 6e 20 73 71 6c 69 74 65  17404} In sqlite
c060: 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
c070: 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
c080: 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
c090: 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
c0a0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
c0b0: 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
c0c0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
c0d0: 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
c0e0: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
c0f0: 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
c100: 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
c110: 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
c120: 61 72 61 6d 65 74 65 72 2e 20 7b 45 4e 44 7d 20  arameter. {END} 
c130: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
c140: 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
c150: 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
c160: 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
c170: 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20  rom snprintf(). 
c180: 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
c190: 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
c1a0: 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
c1b0: 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
c1c0: 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
c1d0: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
c1e0: 69 74 79 2e 20 20 7b 46 31 37 34 30 35 7d 20 4e  ity.  {F17405} N
c1f0: 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
c200: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
c210: 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
c220: 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
c230: 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
c240: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
c250: 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
c260: 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
c270: 20 74 68 65 20 62 75 66 66 65 72 2e 20 7b 45 4e   the buffer. {EN
c280: 44 7d 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  D} We admit that
c290: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
c2a0: 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
c2b0: 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
c2c0: 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
c2d0: 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
c2e0: 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
c2f0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c300: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
c310: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
c320: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
c330: 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
c340: 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20  .**.** {F17406} 
c350: 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
c360: 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
c370: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
c380: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
c390: 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
c3a0: 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
c3b0: 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
c3c0: 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 7b 46 31  -terminated. {F1
c3d0: 37 34 30 37 7d 20 54 68 65 20 66 69 72 73 74 0a  7407} The first.
c3e0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
c3f0: 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
c400: 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
c410: 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
c420: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
c430: 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 7b  o terminator.  {
c440: 45 4e 44 7d 20 53 6f 20 74 68 65 20 6c 6f 6e 67  END} So the long
c450: 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
c460: 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
c470: 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
c480: 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
c490: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
c4a0: 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
c4b0: 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
c4c0: 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
c4d0: 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
c4e0: 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
c4f0: 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
c500: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
c510: 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
c520: 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61 74  al printf format
c530: 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
c540: 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
c550: 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
c560: 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
c570: 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
c580: 2a 2a 0a 2a 2a 20 7b 46 31 37 34 31 30 7d 20 54  **.** {F17410} T
c590: 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
c5a0: 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
c5b0: 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
c5c0: 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
c5d0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
c5e0: 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
c5f0: 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
c600: 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
c610: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
c620: 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
c630: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
c640: 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
c650: 61 6c 2e 20 7b 45 4e 44 7d 20 42 79 20 64 6f 75  al. {END} By dou
c660: 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
c670: 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
c680: 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
c690: 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
c6a0: 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
c6b0: 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
c6c0: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
c6d0: 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f  r example, so so
c6e0: 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  me string variab
c6f0: 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  le contains text
c700: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
c710: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
c720: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
c730: 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
c740: 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
c750: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
c760: 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
c770: 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
c780: 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
c790: 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
c7a0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
c7b0: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
c7c0: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
c7d0: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
c7e0: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
c7f0: 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
c800: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
c810: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
c820: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
c830: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
c840: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
c850: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
c860: 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
c870: 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
c880: 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
c890: 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
c8a0: 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
c8b0: 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
c8c0: 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
c8d0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
c8e0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
c8f0: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
c900: 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
c910: 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
c920: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
c930: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
c940: 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
c950: 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
c960: 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
c970: 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
c980: 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
c990: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
c9a0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
c9b0: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
c9c0: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
c9d0: 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
c9e0: 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
c9f0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
ca00: 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
ca10: 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
ca20: 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
ca30: 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
ca40: 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c  ule you.** shoul
ca50: 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  d always use %q 
ca60: 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
ca70: 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
ca80: 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
ca90: 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  .** literal..**.
caa0: 2a 2a 20 7b 46 31 37 34 31 31 7d 20 54 68 65 20  ** {F17411} The 
cab0: 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
cac0: 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
cad0: 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
cae0: 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
caf0: 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
cb00: 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
cb10: 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20  ing.  Or if the 
cb20: 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
cb30: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73   argument.** lis
cb40: 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
cb50: 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
cb60: 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
cb70: 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e  LL" (without sin
cb80: 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69  gle.** quotes) i
cb90: 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
cba0: 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  Q option. {END} 
cbb0: 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
cbc0: 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
cbd0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
cbe0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
cbf0: 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
cc00: 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
cc10: 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
cc20: 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
cc30: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
cc40: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
cc50: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
cc60: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
cc70: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
cc80: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
cc90: 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
cca0: 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
ccb0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
ccc0: 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
ccd0: 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
cce0: 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
ccf0: 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
cd00: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34  ter..**.** {F174
cd10: 31 32 7d 20 54 68 65 20 22 25 7a 22 20 66 6f 72  12} The "%z" for
cd20: 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
cd30: 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b  orks exactly lik
cd40: 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a  e "%s" with the.
cd50: 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
cd60: 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
cd70: 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
cd80: 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
cd90: 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
cda0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
cdb0: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
cdc0: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b   input string. {
cdd0: 45 4e 44 7d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  END}.*/.char *sq
cde0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
cdf0: 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
ce00: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
ce10: 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
ce20: 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
ce30: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
ce40: 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
ce50: 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
ce60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ce70: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
ce80: 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b  tion Subsystem {
ce90: 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F17300}.**.** {F
cea0: 31 37 33 30 31 7d 20 54 68 65 20 53 51 4c 69 74  17301} The SQLit
ceb0: 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65  e core  uses the
cec0: 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
ced0: 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
cee0: 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
cef0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cf00: 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
cf10: 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
cf20: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
cf30: 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
cf40: 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
cf50: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
cf60: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
cf70: 6e 2e 20 20 54 68 65 0a 2a 2a 20 77 69 6e 64 6f  n.  The.** windo
cf80: 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
cf90: 76 65 20 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 72  ve malloc and fr
cfa0: 65 65 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  ee for some oper
cfb0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ations..**.** {F
cfc0: 31 37 33 30 32 7d 20 54 68 65 20 73 71 6c 69 74  17302} The sqlit
cfd0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
cfe0: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
cff0: 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
d000: 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
d010: 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
d020: 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
d030: 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
d040: 65 72 2e 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20  er..** {F17303} 
d050: 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
d060: 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
d070: 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
d080: 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
d090: 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
d0a0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 7b  NULL pointer.  {
d0b0: 46 31 37 33 30 34 7d 20 49 66 20 74 68 65 20 70  F17304} If the p
d0c0: 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
d0d0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
d0e0: 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
d0f0: 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
d100: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
d110: 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
d120: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  inter..**.** {F1
d130: 37 33 30 35 7d 20 43 61 6c 6c 69 6e 67 20 73 71  7305} Calling sq
d140: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
d150: 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
d160: 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
d170: 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
d180: 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
d190: 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
d1a0: 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
d1b0: 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
d1c0: 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
d1d0: 20 7b 46 31 37 33 30 36 7d 20 54 68 65 20 73 71   {F17306} The sq
d1e0: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
d1f0: 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
d200: 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
d210: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
d220: 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
d230: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
d240: 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
d250: 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
d260: 7b 55 31 37 33 30 37 7d 20 41 66 74 65 72 20 62  {U17307} After b
d270: 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
d280: 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
d290: 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
d2a0: 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
d2b0: 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
d2c0: 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
d2d0: 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
d2e0: 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
d2f0: 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
d300: 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
d310: 2a 20 7b 55 31 37 33 30 39 7d 20 4d 65 6d 6f 72  * {U17309} Memor
d320: 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
d330: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
d340: 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
d350: 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
d360: 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
d370: 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
d380: 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
d390: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
d3a0: 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
d3b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
d3c0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
d3d0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a  sqlite3_free()..
d3e0: 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 54  **.** {F17310} T
d3f0: 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
d400: 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
d410: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
d420: 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
d430: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
d440: 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
d450: 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
d460: 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
d470: 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
d480: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d490: 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
d4a0: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
d4b0: 70 61 72 61 6d 65 74 65 72 2e 20 20 7b 46 31 37  parameter.  {F17
d4c0: 33 31 31 7d 20 49 66 20 74 68 65 20 66 69 72 73  311} If the firs
d4d0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
d4e0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
d4f0: 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
d500: 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
d510: 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
d520: 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
d530: 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
d540: 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
d550: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
d560: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
d570: 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 7b 46  realloc()..** {F
d580: 31 37 33 31 32 7d 20 49 66 20 74 68 65 20 73 65  17312} If the se
d590: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
d5a0: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
d5b0: 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
d5c0: 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
d5d0: 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
d5e0: 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
d5f0: 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
d600: 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
d610: 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
d620: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
d630: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
d640: 28 29 2e 0a 2a 2a 20 7b 46 31 37 33 31 33 7d 20  ()..** {F17313} 
d650: 53 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  Sqlite3_realloc(
d660: 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
d670: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
d680: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
d690: 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
d6a0: 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
d6b0: 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
d6c0: 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
d6d0: 6c 61 62 6c 65 2e 0a 2a 2a 20 7b 46 31 37 33 31  lable..** {F1731
d6e0: 34 7d 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  4} If M is the s
d6f0: 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
d700: 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
d710: 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
d720: 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
d730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
d740: 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
d750: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
d760: 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
d770: 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
d780: 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
d790: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
d7a0: 20 66 72 65 65 64 2e 0a 2a 2a 20 7b 46 31 37 33   freed..** {F173
d7b0: 31 35 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 72  15} If sqlite3_r
d7c0: 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
d7d0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
d7e0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d7f0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
d800: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 36 7d  ..**.** {F17316}
d810: 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75   The memory retu
d820: 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
d830: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
d840: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
d850: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
d860: 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
d870: 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
d880: 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ry. {END}.**.** 
d890: 7b 46 31 37 33 38 31 7d 20 54 68 65 20 64 65 66  {F17381} The def
d8a0: 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
d8b0: 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65  ion.** of the me
d8c0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d8d0: 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74  subsystem uses t
d8e0: 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
d8f0: 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72  lloc().** and fr
d900: 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
d910: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
d920: 6c 69 62 72 61 72 79 2e 20 7b 46 31 37 33 38 32  library. {F17382
d930: 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a  } However, if .*
d940: 2a 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  * SQLite is comp
d950: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 6f  iled with the fo
d960: 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f  llowing C prepro
d970: 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a  cessor macro.**.
d980: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20  ** <blockquote> 
d990: 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
d9a0: 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f  ZE=<i>NNN</i> </
d9b0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
d9c0: 2a 20 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f  * where <i>NNN</
d9d0: 69 3e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  i> is an integer
d9e0: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72  , then SQLite cr
d9f0: 65 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  eate a static.**
da00: 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61   array of at lea
da10: 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79  st <i>NNN</i> by
da20: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20  tes in size and 
da30: 75 73 65 20 74 68 61 74 20 61 72 72 61 79 0a 2a  use that array.*
da40: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
da50: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
da60: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
da70: 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f  . {END}  Additio
da80: 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  nal.** memory al
da90: 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20  locator options 
daa0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
dab0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
dac0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
dad0: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
dae0: 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
daf0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
db00: 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
db10: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
db20: 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
db30: 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
db40: 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
db50: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
db60: 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
db70: 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
db80: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
db90: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
dba0: 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
dbb0: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
dbc0: 63 61 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a  cators can be.**
dbd0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
dbe0: 20 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   windows OS inte
dbf0: 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
dc00: 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
dc10: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
dc20: 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
dc30: 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
dc40: 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
dc50: 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
dc60: 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
dc70: 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
dc80: 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
dc90: 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
dca0: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
dcb0: 77 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  windows.** insta
dcc0: 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
dcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
dce0: 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
dcf0: 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
dd00: 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
dd10: 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
dd20: 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
dd30: 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
dd40: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
dd50: 45 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  EM]..*/.void *sq
dd60: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
dd70: 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
dd80: 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
dd90: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
dda0: 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
ddb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ddc0: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
ddd0: 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 46 31  r Statistics {F1
dde0: 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 61  7370}.**.** In a
ddf0: 64 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62  ddition to the b
de00: 61 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63  asic three alloc
de10: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a  ation routines .
de20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
de30: 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
de40: 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
de50: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
de60: 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
de70: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
de80: 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69  stem included wi
de90: 74 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  th the SQLite.**
dea0: 20 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65   sources provide
deb0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  s the interfaces
dec0: 20 73 68 6f 77 6e 20 68 65 72 65 2e 0a 2a 2a 0a   shown here..**.
ded0: 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 65 20  ** {F17371} The 
dee0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
def0: 73 65 64 28 29 20 72 6f 75 74 69 6e 65 20 72 65  sed() routine re
df00: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
df10: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
df20: 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
df30: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
df40: 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
df50: 72 65 65 64 29 2e 0a 2a 2a 20 7b 46 31 37 33 37  reed)..** {F1737
df60: 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  2} The value ret
df70: 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
df80: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 20 69  _memory_used() i
df90: 6e 63 6c 75 64 65 73 0a 2a 2a 20 61 6e 79 20 6f  ncludes.** any o
dfa0: 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
dfb0: 20 53 51 4c 69 74 65 2c 20 62 75 74 20 6e 6f 74   SQLite, but not
dfc0: 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
dfd0: 62 79 20 74 68 65 0a 2a 2a 20 6c 69 62 72 61 72  by the.** librar
dfe0: 79 20 6d 61 6c 6c 6f 63 28 29 20 74 68 61 74 20  y malloc() that 
dff0: 62 61 63 6b 73 20 74 68 65 20 73 71 6c 69 74 65  backs the sqlite
e000: 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  3_malloc() imple
e010: 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 7b 46  mentation..** {F
e020: 31 37 33 37 33 7d 20 54 68 65 20 73 71 6c 69 74  17373} The sqlit
e030: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
e040: 74 65 72 28 29 20 72 6f 75 74 69 6e 65 73 20 72  ter() routines r
e050: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6d 61  eturns the.** ma
e060: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
e070: 62 79 74 65 73 20 74 68 61 74 20 68 61 76 65 20  bytes that have 
e080: 62 65 65 6e 20 6f 75 74 73 74 61 6e 64 69 6e 67  been outstanding
e090: 20 61 74 20 61 6e 79 20 74 69 6d 65 0a 2a 2a 20   at any time.** 
e0a0: 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 77 61  since the highwa
e0b0: 74 65 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 73  ter mark was las
e0c0: 74 20 72 65 73 65 74 2e 0a 2a 2a 20 7b 46 31 37  t reset..** {F17
e0d0: 33 37 34 7d 20 54 68 65 20 62 79 74 65 20 63 6f  374} The byte co
e0e0: 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
e0f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
e100: 69 67 68 77 61 74 65 72 28 29 0a 2a 2a 20 75 73  ighwater().** us
e110: 65 73 20 74 68 65 20 73 61 6d 65 20 62 79 74 65  es the same byte
e120: 20 63 6f 75 6e 74 69 6e 67 20 72 75 6c 65 73 20   counting rules 
e130: 61 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  as sqlite3_memor
e140: 79 5f 75 73 65 64 28 29 2e 20 7b 45 4e 44 7d 0a  y_used(). {END}.
e150: 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
e160: 73 2c 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  s, overhead adde
e170: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
e180: 53 51 4c 69 74 65 20 69 73 20 63 6f 75 6e 74 65  SQLite is counte
e190: 64 2c 0a 2a 2a 20 62 75 74 20 6f 76 65 72 68 65  d,.** but overhe
e1a0: 61 64 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65  ad from the unde
e1b0: 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6d 61  rlying system ma
e1c0: 6c 6c 6f 63 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20  lloc is not..** 
e1d0: 7b 46 31 37 33 37 35 7d 20 49 66 20 74 68 65 20  {F17375} If the 
e1e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
e1f0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
e200: 77 61 74 65 72 28 29 20 69 73 20 74 72 75 65 2c  water() is true,
e210: 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 68 69 67  .** then the hig
e220: 68 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  hwater mark is r
e230: 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
e240: 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
e250: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
e260: 73 65 64 28 29 20 61 6e 64 20 74 68 65 20 70 72  sed() and the pr
e270: 69 6f 72 20 68 69 67 68 77 61 74 65 72 20 6d 61  ior highwater ma
e280: 72 6b 20 28 62 65 66 6f 72 65 20 74 68 65 0a 2a  rk (before the.*
e290: 2a 20 72 65 73 65 74 29 20 69 73 20 72 65 74 75  * reset) is retu
e2a0: 72 6e 65 64 2e 20 20 7b 46 31 37 33 37 36 7d 20  rned.  {F17376} 
e2b0: 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
e2c0: 72 20 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65 33  r to .** sqlite3
e2d0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
e2e0: 72 28 29 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  r() is zero, the
e2f0: 6e 20 74 68 65 20 68 69 67 68 77 61 74 65 72 20  n the highwater 
e300: 6d 61 72 6b 20 69 73 0a 2a 2a 20 75 6e 63 68 61  mark is.** uncha
e310: 6e 67 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nged..*/.sqlite3
e320: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
e330: 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
e340: 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
e350: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
e360: 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
e370: 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
e380: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
e390: 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
e3a0: 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
e3b0: 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12500}.**.** {F
e3c0: 31 32 35 30 31 7d 20 54 68 69 73 20 72 6f 75 74  12501} This rout
e3d0: 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
e3e0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
e3f0: 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
e400: 63 75 6c 61 72 0a 2a 2a 20 64 61 74 61 62 61 73  cular.** databas
e410: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 73 75  e connection, su
e420: 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
e430: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46  rst argument. {F
e440: 31 32 35 30 32 7d 0a 2a 2a 20 54 68 65 20 61 75  12502}.** The au
e450: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
e460: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
e470: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
e480: 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
e490: 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
e4a0: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
e4b0: 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
e4c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
e4d0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
e4e0: 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
e4f0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
e500: 65 31 36 5f 76 32 28 29 5d 2e 20 20 7b 46 31 32  e16_v2()].  {F12
e510: 35 30 33 7d 20 41 74 20 76 61 72 69 6f 75 73 0a  503} At various.
e520: 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
e530: 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
e540: 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
e550: 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
e560: 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
e570: 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
e580: 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
e590: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
e5a0: 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
e5b0: 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
e5c0: 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
e5d0: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
e5e0: 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
e5f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
e600: 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  K to allow the a
e610: 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
e620: 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
e630: 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
e640: 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
e650: 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
e660: 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
e670: 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
e680: 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
e690: 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
e6a0: 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
e6b0: 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
e6c0: 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
e6d0: 6e 20 65 72 72 6f 72 2e 20 20 7b 46 31 32 35 30  n error.  {F1250
e6e0: 34 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  4} If the author
e6f0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
e700: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
e710: 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
e720: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
e730: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
e740: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
e750: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  then [sqlite3_pr
e760: 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
e770: 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
e780: 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
e790: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
e7a0: 73 68 61 6c 6c 0a 2a 2a 20 66 61 69 6c 20 77 69  shall.** fail wi
e7b0: 74 68 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  th an SQLITE_ERR
e7c0: 4f 52 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  OR error code an
e7d0: 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
e7e0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
e7f0: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  {END}.**.** When
e800: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
e810: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
e820: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
e830: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
e840: 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
e850: 20 7b 46 31 32 35 30 35 7d 20 57 68 65 6e 20 74   {F12505} When t
e860: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
e870: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
e880: 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
e890: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
e8a0: 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
e8b0: 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
e8c0: 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
e8d0: 69 7a 65 72 20 73 68 61 6c 6c 20 66 61 69 6c 0a  izer shall fail.
e8e0: 2a 2a 20 77 69 74 68 20 61 6e 20 53 51 4c 49 54  ** with an SQLIT
e8f0: 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 20 63 6f  E_ERROR error co
e900: 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  de and an error 
e910: 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
e920: 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
e930: 73 20 69 73 20 64 65 6e 69 65 64 2e 20 7b 46 31  s is denied. {F1
e940: 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74  2506} If the aut
e950: 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68  horizer code (th
e960: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
e970: 2a 2a 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  ** to the author
e980: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
e990: 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20   anything other 
e9a0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41  than [SQLITE_REA
e9b0: 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 72 65  D], then.** a re
e9c0: 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  turn of [SQLITE_
e9d0: 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20  IGNORE] has the 
e9e0: 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b  same effect as [
e9f0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a  SQLITE_DENY]. .*
ea00: 2a 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  * If the authori
ea10: 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  zer code is [SQL
ea20: 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
ea30: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
ea40: 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
ea50: 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70  NORE] then the p
ea60: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
ea70: 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
ea80: 20 74 6f 0a 2a 2a 20 69 6e 73 65 72 74 20 61 20   to.** insert a 
ea90: 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
eaa0: 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
eab0: 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
eac0: 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
ead0: 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
eae0: 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
eaf0: 75 72 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  urned. {END}.**.
eb00: 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 65 20  ** {F12510} The 
eb10: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
eb20: 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
eb30: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
eb40: 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74  copy of.** the t
eb50: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
eb60: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
eb70: 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
eb80: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 7b 46 31  nterface..** {F1
eb90: 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2511} The second
eba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
ebb0: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
ebc0: 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51   integer .** [SQ
ebd0: 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
ebe0: 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
ebf0: 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74  ecifies the part
ec00: 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a  icular action.**
ec10: 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
ec20: 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 76 61  d. {END} The ava
ec30: 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f  ilable action co
ec40: 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49  des are.** [SQLI
ec50: 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65  TE_COPY | docume
ec60: 6e 74 65 64 20 73 65 70 61 72 61 74 65 6c 79 5d  nted separately]
ec70: 2e 20 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20  .  {F12512} The 
ec80: 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
ec90: 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  xth.** parameter
eca0: 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
ecb0: 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
ecc0: 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
ecd0: 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61  at contain .** a
ece0: 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
ecf0: 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
ed00: 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
ed10: 7a 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  zed. {END}.**.**
ed20: 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
ed30: 73 20 75 73 65 64 20 77 68 65 6e 20 70 72 65 70  s used when prep
ed40: 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  aring SQL statem
ed50: 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
ed60: 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65  rusted.** source
ed70: 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
ed80: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
ed90: 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  nts do not try t
eda0: 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a  o access data.**
edb0: 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20 6e   that they are n
edc0: 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
edd0: 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
ede0: 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a  do not try to.**
edf0: 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
ee00: 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
ee10: 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
ee20: 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
ee30: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
ee40: 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
ee50: 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
ee60: 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
ee70: 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
ee80: 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
ee90: 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
eea0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
eeb0: 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
eec0: 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
eed0: 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
eee0: 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
eef0: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
ef00: 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
ef10: 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
ef20: 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
ef30: 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
ef40: 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
ef50: 67 20 70 72 65 70 61 72 65 64 20 74 68 61 74 20  g prepared that 
ef60: 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
ef70: 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20 53  hing.** except S
ef80: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
ef90: 2e 20 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  .  .**.** {F1252
efa0: 30 7d 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  0} Only a single
efb0: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
efc0: 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
efd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
efe0: 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
eff0: 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
f000: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
f010: 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
f020: 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
f030: 73 20 63 61 6c 6c 2e 20 7b 46 31 32 35 32 31 7d  s call. {F12521}
f040: 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69    A NULL authori
f050: 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
f060: 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
f070: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ** callback is i
f080: 6e 76 6f 6b 65 64 2e 20 20 7b 46 31 32 35 32 32  nvoked.  {F12522
f090: 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75  } The default au
f0a0: 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c  thorizer is NULL
f0b0: 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 4e 6f  . {END}.**.** No
f0c0: 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
f0d0: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
f0e0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
f0f0: 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  during .** [sqli
f100: 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
f110: 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
f120: 20 7b 46 31 32 35 32 33 7d 20 41 75 74 68 6f 72   {F12523} Author
f130: 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
f140: 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
f150: 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
f160: 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
f170: 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 7b 45 4e  te3_step()]. {EN
f180: 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D}.*/.int sqlite
f190: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
f1a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
f1b0: 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
f1c0: 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
f1d0: 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
f1e0: 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
f1f0: 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
f200: 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
f210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
f220: 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
f230: 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a   Codes {F12590}.
f240: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
f250: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
f260: 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
f270: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
f280: 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
f290: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
f2a0: 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
f2b0: 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
f2c0: 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
f2d0: 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
f2e0: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
f2f0: 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
f300: 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
f310: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
f320: 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
f330: 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
f340: 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
f350: 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
f360: 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
f370: 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
f380: 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
f390: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
f3a0: 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
f3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
f3c0: 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
f3d0: 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
f3e0: 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
f3f0: 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
f400: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f410: 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
f420: 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d  n Codes {F12550}
f430: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
f440: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
f450: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
f460: 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
f470: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
f480: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
f490: 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63   to authorizer c
f4a0: 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
f4b0: 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 7b  ment actions.  {
f4c0: 46 31 32 35 35 31 7d 20 54 68 65 0a 2a 2a 20 73  F12551} The.** s
f4d0: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
f4e0: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
f4f0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
f500: 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
f510: 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
f520: 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
f530: 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
f540: 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
f550: 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
f560: 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
f570: 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
f580: 20 70 61 73 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a   passed. {END}.*
f590: 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
f5a0: 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
f5b0: 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
f5c0: 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
f5d0: 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72  to be .** author
f5e0: 69 7a 65 64 2e 20 20 7b 46 31 32 35 35 32 7d 20  ized.  {F12552} 
f5f0: 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
f600: 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
f610: 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
f620: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
f630: 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
f640: 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
f650: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
f660: 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
f670: 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
f680: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
f690: 65 74 65 72 2e 20 7b 46 31 32 35 35 33 7d 20 54  eter. {F12553} T
f6a0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
f6b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
f6c0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
f6d0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
f6e0: 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
f6f0: 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20  n", "temp", .** 
f700: 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
f710: 62 6c 65 2e 20 7b 46 31 32 35 35 34 7d 20 54 68  ble. {F12554} Th
f720: 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
f730: 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
f740: 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
f750: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
f760: 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
f770: 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
f780: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
f790: 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
f7a0: 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
f7b0: 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
f7c0: 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
f7d0: 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f  ctly from .** to
f7e0: 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
f7f0: 2e 0a 2a 2f 0a 2f 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 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
f820: 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
f830: 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
f840: 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
f850: 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
f860: 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
f870: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
f880: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
f890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f8a0: 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
f8b0: 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
f8c0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
f8d0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
f8e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f8f0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
f900: 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
f910: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
f920: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
f930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f940: 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
f950: 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
f960: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
f970: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
f980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f990: 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
f9a0: 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
f9b0: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
f9c0: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
f9d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
f9e0: 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
f9f0: 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
fa00: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
fa10: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
fa20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
fa30: 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
fa40: 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
fa50: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
fa60: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
fa70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
fa80: 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
fa90: 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
faa0: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
fab0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
fac0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
fad0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
fae0: 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
faf0: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
fb00: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
fb10: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
fb20: 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
fb30: 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
fb40: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
fb50: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
fb60: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
fb70: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
fb80: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
fb90: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
fba0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
fbb0: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
fbc0: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
fbd0: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
fbe0: 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
fbf0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
fc00: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
fc10: 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
fc20: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
fc30: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
fc40: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
fc50: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
fc60: 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
fc70: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
fc80: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
fc90: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
fca0: 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
fcb0: 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
fcc0: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
fcd0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
fce0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
fcf0: 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
fd00: 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
fd10: 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
fd20: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
fd30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
fd40: 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
fd50: 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
fd60: 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
fd70: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
fd80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fd90: 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
fda0: 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
fdb0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
fdc0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
fdd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fde0: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
fdf0: 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
fe00: 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
fe10: 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
fe20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fe30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
fe40: 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
fe50: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
fe60: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
fe70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
fe80: 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
fe90: 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
fea0: 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
feb0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
fec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
fed0: 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
fee0: 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
fef0: 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
ff00: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
ff10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
ff20: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
ff30: 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
ff40: 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
ff50: 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
ff60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
ff70: 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
ff80: 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
ff90: 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
ffa0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
ffb0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
ffc0: 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
ffd0: 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
ffe0: 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
fff0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
10000 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
10010 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
10020 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
10030 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
10040 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
10050 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
10060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
10070 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
10080 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
10090 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
100a0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
100b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
100c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
100d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
100e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
100f0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
10100 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
10110 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
10120 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
10130 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
10140 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
10150 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
10160 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
10170 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
10180 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
10190 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
101a0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
101b0 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
101c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
101d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
101e0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
101f0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
10200 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
10210 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10220 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
10230 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
10240 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a  ons {F12280}.**.
10250 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
10260 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
10270 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
10280 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
10290 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
102a0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
102b0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
102c0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
102d0 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20  ** {F12281} The 
102e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
102f0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
10300 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
10310 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74  is invoked.** at
10320 20 74 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69   the first [sqli
10330 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
10340 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
10350 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
10360 6e 74 2e 0a 2a 2a 20 7b 46 31 32 32 38 32 7d 20  nt..** {F12282} 
10370 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 74 72  Only a single tr
10380 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  ace callback can
10390 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
103a0 74 20 61 20 74 69 6d 65 2e 0a 2a 2a 20 45 61 63  t a time..** Eac
103b0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
103c0 33 5f 74 72 61 63 65 28 29 20 6f 76 65 72 72 69  3_trace() overri
103d0 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73  des the previous
103e0 2e 20 20 7b 46 31 32 32 38 33 7d 20 41 0a 2a 2a  .  {F12283} A.**
103f0 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 20 66   NULL callback f
10400 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
10410 28 29 20 64 69 73 61 62 6c 65 73 20 74 72 61 63  () disables trac
10420 69 6e 67 2e 20 20 7b 46 31 32 32 38 34 7d 20 54  ing.  {F12284} T
10430 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
10440 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
10450 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
10460 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e  copy of the poin
10470 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 77 61 73  ter which.** was
10480 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
10490 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  t to sqlite3_tra
104a0 63 65 2e 20 20 7b 46 31 32 32 38 35 7d 20 54 68  ce.  {F12285} Th
104b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
104c0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 74 72 61 63  t.** to the trac
104d0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
104e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
104f0 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74  UTF8 string cont
10500 61 69 6e 69 6e 67 0a 2a 2a 20 74 68 65 20 6f 72  aining.** the or
10510 69 67 69 6e 61 6c 20 74 65 78 74 20 6f 66 20 74  iginal text of t
10520 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
10530 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65   as it was passe
10540 64 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  d into.** [sqlit
10550 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
10560 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
10570 6e 74 2e 20 7b 45 4e 44 7d 20 20 4e 6f 74 65 20  nt. {END}  Note 
10580 74 68 61 74 20 74 68 65 0a 2a 2a 20 68 6f 73 74  that the.** host
10590 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 6e   parameter are n
105a0 6f 74 20 65 78 70 61 6e 64 65 64 20 69 6e 20 74  ot expanded in t
105b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
105c0 20 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   text..**.** {F1
105d0 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61  2287} The callba
105e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
105f0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
10600 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
10610 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
10620 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
10630 66 69 6e 69 73 68 65 73 2e 20 20 7b 46 31 32 32  finishes.  {F122
10640 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  88} The first pa
10650 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
10660 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  * profile callba
10670 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
10680 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
10690 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f  r to sqlite3_pro
106a0 66 69 6c 65 28 29 2e 0a 2a 2a 20 7b 46 31 32 32  file()..** {F122
106b0 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  89} The second p
106c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
106d0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
106e0 20 69 73 20 61 0a 2a 2a 20 7a 65 72 6f 2d 74 65   is a.** zero-te
106f0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
10700 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
10710 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
10720 20 74 65 78 74 20 6f 66 0a 2a 2a 20 74 68 65 20   text of.** the 
10730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
10740 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65   it was processe
10750 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
10760 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
10770 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  * the equivalent
10780 2e 20 20 7b 46 31 32 32 39 30 7d 20 54 68 65 20  .  {F12290} The 
10790 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
107a0 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 0a  to the profile .
107b0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
107c0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
107d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
107e0 73 65 63 6f 6e 64 73 20 6f 66 0a 2a 2a 20 77 61  seconds of.** wa
107f0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65  ll-clock time re
10800 71 75 69 72 65 64 20 74 6f 20 72 75 6e 20 74 68  quired to run th
10810 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
10820 66 72 6f 6d 20 73 74 61 72 74 0a 2a 2a 20 74 6f  from start.** to
10830 20 66 69 6e 69 73 68 2e 20 7b 45 4e 44 7d 20 20   finish. {END}  
10840 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10850 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49  e3_profile() API
10860 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
10870 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
10880 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20  ental and.** is 
10890 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
108a0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
108b0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
108c0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
108d0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
108e0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  ar*), void*);.vo
108f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
10900 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
10910 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
10920 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
10930 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
10940 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
10950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
10960 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
10970 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a  backs {F12910}.*
10980 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68  *.** {F12911} Th
10990 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
109a0 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
109b0 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
109c0 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
109d0 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
109e0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
109f0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
10a00 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
10a10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
10a20 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
10a30 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
10a40 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
10a50 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 41 6e 20 65  ()]. {END}  An e
10a60 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
10a70 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63  his .** interfac
10a80 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
10a90 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
10aa0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
10ab0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20  .**.** {F12912} 
10ac0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
10ad0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
10ae0 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20   once for every 
10af0 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  N virtual.** mac
10b00 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68  hine opcodes, wh
10b10 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
10b20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
10b30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
10b40 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70  * {F12913} The p
10b50 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
10b60 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74   itself is ident
10b70 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69  ified by the thi
10b80 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
10b90 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
10ba0 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f   {F12914} The fo
10bb0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
10bc0 20 74 68 69 73 0a 2a 2a 20 66 75 6e 63 74 69 6f   this.** functio
10bd0 6e 20 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e  n is a void poin
10be0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
10bf0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
10c00 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
10c10 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
10c20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a  invoked. {END}.*
10c30 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66  *.** {F12915} If
10c40 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
10c50 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
10c60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f  lite3_step()], o
10c70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  r.** [sqlite3_ge
10c80 74 5f 74 61 62 6c 65 28 29 5d 20 72 65 73 75 6c  t_table()] resul
10c90 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e  ts in fewer than
10ca0 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67   N opcodes being
10cb0 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 74 68   executed,.** th
10cc0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  en the progress 
10cd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65  callback is neve
10ce0 72 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d  r invoked. {END}
10cf0 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d  .** .** {F12916}
10d00 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70   Only a single p
10d10 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
10d20 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
10d30 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20   registered for 
10d40 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74  each.** open dat
10d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10d60 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f  .  Every call to
10d70 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
10d80 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f  s_handler().** o
10d90 76 65 72 77 72 69 74 65 73 20 74 68 65 20 72 65  verwrites the re
10da0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70 72 65  sults of the pre
10db0 76 69 6f 75 73 20 63 61 6c 6c 2e 20 7b 46 31 32  vious call. {F12
10dc0 39 31 37 7d 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76  917}.** To remov
10dd0 65 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  e the progress c
10de0 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 68  allback altogeth
10df0 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 73  er, pass NULL as
10e00 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
10e10 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
10e20 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a  unction. {END}.*
10e30 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49 66  *.** {F12918} If
10e40 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
10e50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
10e60 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
10e70 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  an 0, then.** th
10e80 65 20 63 75 72 72 65 6e 74 20 71 75 65 72 79 20  e current query 
10e90 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 74  is immediately t
10ea0 65 72 6d 69 6e 61 74 65 64 20 61 6e 64 20 61 6e  erminated and an
10eb0 79 20 64 61 74 61 62 61 73 65 20 63 68 61 6e 67  y database chang
10ec0 65 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  es.** rolled bac
10ed0 6b 2e 20 7b 46 31 32 39 31 39 7d 0a 2a 2a 20 54  k. {F12919}.** T
10ee0 68 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73  he containing [s
10ef0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
10f00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
10f10 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
10f20 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61  _get_table()] ca
10f30 6c 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ll returns SQLIT
10f40 45 5f 49 4e 54 45 52 52 55 50 54 2e 20 7b 45 4e  E_INTERRUPT. {EN
10f50 44 7d 20 20 54 68 69 73 20 66 65 61 74 75 72 65  D}  This feature
10f60 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
10f70 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
10f80 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 22   implement the "
10f90 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
10fa0 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  n a.** progress 
10fb0 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20  dialog box in a 
10fc0 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  GUI..*/.void sql
10fd0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
10fe0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
10ff0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
11000 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
11010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
11020 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
11030 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b  ase Connection {
11040 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12700}.**.** {F
11050 31 32 37 30 31 7d 20 54 68 65 73 65 20 72 6f 75  12701} These rou
11060 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
11070 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
11080 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a  le whose name.**
11090 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
110a0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
110b0 6e 74 2e 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20  nt..** {F12702} 
110c0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
110d0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
110e0 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
110f0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
11100 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
11110 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e  e3_open_v2()] an
11120 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69  d as UTF-16.** i
11130 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
11140 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
11150 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
11160 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 6e 20 5b  ** {F12703} An [
11170 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
11180 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20   is returned in 
11190 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69  *ppDb, even.** i
111a0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
111b0 73 2e 20 20 7b 46 31 32 37 32 33 7d 20 28 45 78  s.  {F12723} (Ex
111c0 63 65 70 74 69 6f 6e 3a 20 69 66 20 53 51 4c 69  ception: if SQLi
111d0 74 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  te is unable.** 
111e0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
111f0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
11200 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
11210 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20   a NULL will.** 
11220 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
11230 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
11240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
11250 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
11260 63 74 2e 29 0a 2a 2a 20 7b 46 31 32 37 30 34 7d  ct.).** {F12704}
11270 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
11280 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
11290 6f 72 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 73  or created).** s
112a0 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
112b0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  n [SQLITE_OK] is
112c0 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 32   returned.  {F12
112d0 37 30 35 7d 20 4f 74 68 65 72 77 69 73 65 20 61  705} Otherwise a
112e0 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
112f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46  is returned.  {F
11300 31 32 37 30 36 7d 20 54 68 65 0a 2a 2a 20 5b 73  12706} The.** [s
11310 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
11320 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
11330 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e  msg16()]  routin
11340 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
11350 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
11360 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
11370 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
11380 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  he error..**.** 
11390 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64 65 66  {F12707} The def
113a0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
113b0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
113c0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
113d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
113e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
113f0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61  open_v2()] is ca
11400 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
11410 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
11420 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b   byte order if [
11430 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
11440 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ] is used..**.**
11450 20 7b 46 31 32 37 30 38 7d 20 57 68 65 74 68 65   {F12708} Whethe
11460 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
11470 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
11480 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
11490 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
114a0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71  ted with the [sq
114b0 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73  lite3*] handle s
114c0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
114d0 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a  d by passing it.
114e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
114f0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
11500 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
11510 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  uired..**.** {F1
11520 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  2709} The [sqlit
11530 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
11540 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
11550 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ke [sqlite3_open
11560 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20 74  ()] .** except t
11570 68 61 74 20 69 74 20 61 63 63 63 65 70 74 73 20  hat it acccepts 
11580 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
11590 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
115a0 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
115b0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
115c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
115d0 74 69 6f 6e 2e 20 20 7b 46 31 32 37 31 30 7d 20  tion.  {F12710} 
115e0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
115f0 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e  ter can be.** on
11600 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  e of:.**.** <ol>
11610 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
11620 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
11630 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
11640 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
11650 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
11660 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
11670 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
11680 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f  N_CREATE].** </o
11690 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31  l>.**.** {F12711
116a0 7d 20 54 68 65 20 66 69 72 73 74 20 76 61 6c 75  } The first valu
116b0 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61  e opens the data
116c0 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20  base read-only. 
116d0 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20  .** {F12712} If 
116e0 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
116f0 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  s not previously
11700 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
11710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
11720 20 7b 46 31 32 37 31 33 7d 20 54 68 65 20 73 65   {F12713} The se
11730 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e  cond option open
11740 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
11750 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
11760 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
11770 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
11780 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20  g only if.** if 
11790 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
117a0 65 20 70 72 6f 74 65 63 74 65 64 2e 20 20 7b 46  e protected.  {F
117b0 31 32 37 31 34 7d 20 49 6e 20 65 69 74 68 65 72  12714} In either
117c0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
117d0 73 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61  se.** must alrea
117e0 64 79 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65  dy exist or an e
117f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
11800 2e 20 20 7b 46 31 32 37 31 35 7d 20 54 68 65 20  .  {F12715} The 
11810 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20  third option.** 
11820 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
11830 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
11840 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63  nd writing and c
11850 72 65 61 74 65 73 20 69 74 20 69 66 20 69 74 20  reates it if it 
11860 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65  does.** not alre
11870 61 64 79 20 65 78 69 73 74 2e 20 7b 46 31 32 37  ady exist. {F127
11880 31 36 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  16}.** The third
11890 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61   options is beha
118a0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
118b0 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71  ays used for [sq
118c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
118d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
118e0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  en16()]..**.** {
118f0 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66  F12717} If the f
11900 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
11910 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
11920 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d  rivate.** in-mem
11930 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20  ory database is 
11940 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
11950 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 7b 46 31 32  connection. {F12
11960 37 31 38 7d 20 54 68 69 73 20 69 6e 2d 6d 65 6d  718} This in-mem
11970 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ory.** database 
11980 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
11990 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
119a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
119b0 65 64 2e 20 7b 45 4e 44 7d 20 20 46 75 74 75 72  ed. {END}  Futur
119c0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
119d0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b  SQLite might mak
119e0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
119f0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
11a00 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65  names.** that be
11a10 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
11a20 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20   character.  It 
11a30 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
11a40 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64  hat .** when a d
11a50 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
11a60 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67   really does beg
11a70 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74  in with.** ":" t
11a80 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74  hat you prefix t
11a90 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
11aa0 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65   a pathname like
11ab0 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69   "./" to.** avoi
11ac0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
11ad0 2a 2a 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74  ** {F12719} If t
11ae0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
11af0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
11b00 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 20 74  then a private t
11b10 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
11b20 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
11b30 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 7b  l be created.  {
11b40 46 31 32 37 32 30 7d 20 54 68 69 73 20 70 72 69  F12720} This pri
11b50 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
11b60 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
11b70 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
11b80 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
11b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11ba0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
11bb0 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65 20  ** {F12721} The 
11bc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
11bd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
11be0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
11bf0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
11c00 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
11c10 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
11c20 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
11c30 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  em .** interface
11c40 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61   that the new da
11c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11c60 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 7b  n should use.  {
11c70 46 31 32 37 32 32 7d 20 49 66 20 74 68 65 0a 2a  F12722} If the.*
11c80 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
11c90 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  er is a NULL poi
11ca0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
11cb0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
11cc0 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  fs].** object is
11cd0 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a   used. {END}.**.
11ce0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69  ** <b>Note to wi
11cf0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
11d00 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
11d10 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
11d20 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
11d30 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
11d40 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
11d50 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73  3_open_v2()] mus
11d60 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
11d70 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
11d80 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
11d90 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
11da0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
11db0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
11dc0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
11dd0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
11de0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
11df0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
11e00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  to.** [sqlite3_o
11e10 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
11e20 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a  e3_open_v2()]..*
11e30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
11e40 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
11e50 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
11e60 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
11e70 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
11e80 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
11e90 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
11ea0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
11eb0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
11ec0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
11ed0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
11ee0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
11ef0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
11f00 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
11f10 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
11f20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
11f30 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
11f40 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
11f50 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
11f60 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
11f70 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
11f80 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
11f90 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
11fa0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
11fb0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
11fc0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
11fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11fe0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
11ff0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
12000 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
12010 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
12020 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
12030 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
12040 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
12050 20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12800}.**.** 
12060 7b 46 31 32 38 30 31 7d 20 54 68 65 20 73 71 6c  {F12801} The sql
12070 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
12080 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
12090 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20   the numeric.** 
120a0 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
120b0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51  ult code] or [SQ
120c0 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
120d0 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
120e0 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74  t code].** for t
120f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
12100 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
12110 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  API call associa
12120 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c  ted.** with [sql
12130 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62  ite3] handle 'db
12140 27 2e 20 7b 55 31 32 38 30 32 7d 20 49 66 20 61  '. {U12802} If a
12150 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
12160 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a  failed but the.*
12170 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  * most recent AP
12180 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
12190 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
121a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
121b0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20  errcode().** is 
121c0 75 6e 64 65 66 69 6e 65 64 2e 20 7b 45 4e 44 7d  undefined. {END}
121d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20  .**.** {F12803} 
121e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
121f0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
12200 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
12210 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
12220 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
12230 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
12240 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
12250 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65  UTF8 or UTF16 re
12260 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 7b  spectively..** {
12270 46 31 32 38 30 34 7d 20 4d 65 6d 6f 72 79 20 74  F12804} Memory t
12280 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
12290 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
122a0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
122b0 6e 61 6c 6c 79 2e 0a 2a 2a 20 7b 55 31 32 38 30  nally..** {U1280
122c0 35 7d 20 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e  5} The .** strin
122d0 67 20 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69  g may be overwri
122e0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
122f0 74 65 64 20 62 79 20 73 75 62 73 65 71 75 65 6e  ted by subsequen
12300 74 20 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74  t calls to SQLit
12310 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
12320 75 6e 63 74 69 6f 6e 73 2e 20 7b 45 4e 44 7d 0a  unctions. {END}.
12330 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 36 7d 20 43  **.** {F12806} C
12340 61 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c  alls to many sql
12350 69 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73  ite3_* functions
12360 20 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 63   set the error c
12370 6f 64 65 20 61 6e 64 0a 2a 2a 20 73 74 72 69 6e  ode and.** strin
12380 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  g returned by [s
12390 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
123a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
123b0 73 67 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  sg()], and.** [s
123c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
123d0 29 5d 20 6f 76 65 72 77 72 69 74 69 6e 67 20 74  )] overwriting t
123e0 68 65 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75  he previous valu
123f0 65 73 2e 20 20 7b 46 31 32 38 30 37 7d 0a 2a 2a  es.  {F12807}.**
12400 20 45 78 63 65 70 74 2c 20 63 61 6c 6c 73 20 74   Except, calls t
12410 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
12420 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  de()],.** [sqlit
12430 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
12440 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
12450 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c 76 65  g16()] themselve
12460 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63 74 20  s do not affect 
12470 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20 6f  the.** results o
12480 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63 61 74  f future invocat
12490 69 6f 6e 73 2e 20 20 7b 46 31 32 38 30 38 7d 20  ions.  {F12808} 
124a0 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
124b0 74 69 6e 65 73 20 74 68 61 74 0a 2a 2a 20 64 6f  tines that.** do
124c0 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65   not return an e
124d0 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70  rror code (examp
124e0 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  le: [sqlite3_dat
124f0 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e  a_count()]) do n
12500 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ot.** change the
12510 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75   error code retu
12520 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
12530 74 69 6e 65 2e 20 20 7b 46 31 32 38 30 39 7d 20  tine.  {F12809} 
12540 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 0a  Interfaces that.
12550 2a 2a 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63  ** are not assoc
12560 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65  iated with a spe
12570 63 69 66 69 63 20 64 61 74 61 62 61 73 65 20 63  cific database c
12580 6f 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d 70  onnection (examp
12590 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  les:.** [sqlite3
125a0 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b  _mprintf()] or [
125b0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
125c0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20 64  hared_cache()] d
125d0 6f 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  o not change.** 
125e0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  the return code.
125f0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
12600 32 38 31 30 7d 20 41 73 73 75 6d 69 6e 67 20 6e  2810} Assuming n
12610 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76 65 6e  o other interven
12620 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ing sqlite3_* AP
12630 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61 64 65  I calls are made
12640 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
12650 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ode returned by 
12660 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
12670 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
12680 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 65 72 72   the same.** err
12690 6f 72 20 61 73 20 74 68 65 20 73 74 72 69 6e 67  or as the string
126a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
126b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
126c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
126d0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  rmsg16()]..*/.in
126e0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
126f0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
12700 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
12710 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
12720 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
12730 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
12740 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
12750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
12760 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
12770 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 0a  ect {F13000}.**.
12780 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
12790 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
127a0 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53  present single S
127b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
127c0 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69  This.** object i
127d0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
127e0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
127f0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
12800 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53   .** "compiled S
12810 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
12820 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
12830 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a  atement"..** .**
12840 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
12850 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
12860 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
12870 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
12880 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
12890 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
128a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
128b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
128c0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
128d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
128e0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
128f0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
12900 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  s using.**      
12910 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
12920 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
12930 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e  d_* interfaces].
12940 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
12950 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
12960 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
12970 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
12980 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
12990 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
129a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
129b0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
129c0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
129d0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
129e0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
129f0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
12a00 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
12a10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
12a20 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
12a30 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
12a40 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
12a50 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
12a60 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
12a70 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
12a80 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
12a90 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
12aa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
12ab0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
12ac0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
12ad0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
12ae0 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a  ement {F13010}.*
12af0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
12b00 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
12b10 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
12b20 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
12b30 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
12b40 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
12b50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
12b60 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d   .**.** {F13011}
12b70 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12b80 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b  ent "db" is an [
12b90 73 71 6c 69 74 65 33 20 7c 20 53 51 4c 69 74 65  sqlite3 | SQLite
12ba0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
12bb0 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ] .** obtained f
12bc0 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c  rom a prior call
12bd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
12be0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
12bf0 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  pen_v2()].** or 
12c00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
12c10 29 5d 2e 20 7b 46 31 33 30 31 32 7d 0a 2a 2a 20  )]. {F13012}.** 
12c20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
12c30 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68  ent "zSql" is th
12c40 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
12c50 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
12c60 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
12c70 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
12c80 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
12c90 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
12ca0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
12cb0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
12cc0 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73  uses UTF-8 and s
12cd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
12ce0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
12cf0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
12d00 20 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e   use UTF-16. {EN
12d10 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33  D}.**.** {F13013
12d20 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
12d30 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a  rgument is less.
12d40 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ** than zero, th
12d50 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
12d60 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
12d70 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
12d80 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66 20  .** {F13014} If 
12d90 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
12da0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
12db0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  s the maximum nu
12dc0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65  mber of .** byte
12dd0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
12de0 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73  .  When nByte is
12df0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
12e00 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
12e10 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
12e20 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
12e30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
12e40 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75  aracter or .** u
12e50 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d 74  ntil the nByte-t
12e60 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
12e70 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b  r comes first. {
12e80 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  END}.**.** {F130
12e90 31 35 7d 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  15} *pzTail is m
12ea0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
12eb0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70  the first byte p
12ec0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
12ed0 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20  he.** first SQL 
12ee0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
12ef0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
12f00 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73  es only compiles
12f10 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74   the first.** st
12f20 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
12f30 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
12f40 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
12f50 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20  what remains.** 
12f60 75 6e 63 6f 6d 70 69 6c 65 64 2e 20 7b 45 4e 44  uncompiled. {END
12f70 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d  }.**.** {F13016}
12f80 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
12f90 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
12fa0 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c  ompiled .** [sql
12fb0 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
12fc0 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74  statement struct
12fd0 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ure] that can be
12fe0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
12ff0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
13000 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
13010 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
13020 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a  ppStmt may be.**
13030 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 7b   set to NULL.  {
13040 46 31 33 30 31 37 7d 20 49 66 20 74 68 65 20 69  F13017} If the i
13050 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
13060 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
13070 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e  e input.** is an
13080 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  d empty string o
13090 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
130a0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
130b0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31   to NULL..** {U1
130c0 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
130d0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
130e0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
130f0 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63  eleting the.** c
13100 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
13110 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  ement.** using [
13120 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
13130 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
13140 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
13150 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39  t..**.** {F13019
13160 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  } On success, [S
13170 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
13180 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
13190 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  e an .** [SQLITE
131a0 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63  _ERROR | error c
131b0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
131c0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
131d0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
131e0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
131f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
13200 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
13210 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
13220 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
13230 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
13240 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
13250 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
13260 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
13270 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
13280 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
13290 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 7b 46 31  couraged..** {F1
132a0 33 30 32 30 7d 20 49 6e 20 74 68 65 20 22 76 32  3020} In the "v2
132b0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
132c0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
132d0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
132e0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
132f0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
13300 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
13310 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20  copy of the .** 
13320 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
13330 74 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63 61  t. {END} This ca
13340 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
13350 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
13360 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
13370 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69   a differently i
13380 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a  n two ways:.**.*
13390 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 7b 46  * <ol>.** <li>{F
133a0 31 33 30 32 32 7d 0a 2a 2a 20 49 66 20 74 68 65  13022}.** If the
133b0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
133c0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
133d0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
133e0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
133f0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
13400 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
13410 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
13420 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
13430 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
13440 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
13450 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
13460 61 67 61 69 6e 2e 20 7b 46 31 32 30 32 33 7d 20  again. {F12023} 
13470 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61  If the schema ha
13480 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20  s changed in.** 
13490 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  a way that makes
134a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e   the statement n
134b0 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20  o longer valid, 
134c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
134d0 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72   will still.** r
134e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43  eturn [SQLITE_SC
134f0 48 45 4d 41 5d 2e 20 20 7b 45 4e 44 7d 20 42 75  HEMA].  {END} Bu
13500 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67  t unlike the leg
13510 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a  acy behavior, .*
13520 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  * [SQLITE_SCHEMA
13530 5d 20 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c  ] is now a fatal
13540 20 65 72 72 6f 72 2e 20 20 7b 46 31 32 30 32 34   error.  {F12024
13550 7d 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71  } Calling.** [sq
13560 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
13570 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e  ()] again will n
13580 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65  ot make the.** e
13590 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 7b  rror go away.  {
135a0 46 31 32 30 32 35 7d 20 4e 6f 74 65 3a 20 75 73  F12025} Note: us
135b0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
135c0 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
135d0 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
135e0 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
135f0 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
13600 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
13610 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a   return. {END}.*
13620 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
13630 69 3e 0a 2a 2a 20 7b 46 31 33 30 33 30 7d 20 57  i>.** {F13030} W
13640 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
13650 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  urs, .** [sqlite
13660 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
13670 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
13680 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 53   detailed .** [S
13690 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
136a0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
136b0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
136c0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
136d0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
136e0 7b 46 31 33 30 33 31 7d 0a 2a 2a 20 54 68 65 20  {F13031}.** The 
136f0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
13700 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  was that [sqlite
13710 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
13720 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
13730 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45  neric.** [SQLITE
13740 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
13750 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c  ode and you woul
13760 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
13770 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a   second call to.
13780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
13790 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  t()] in order to
137a0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
137b0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
137c0 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 7b 46  e problem..** {F
137d0 31 33 30 33 32 7d 0a 2a 2a 20 57 69 74 68 20 74  13032}.** With t
137e0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20  he "v2" prepare 
137f0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
13800 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
13810 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
13820 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  is.** returned i
13830 6d 6d 65 64 69 61 74 65 6c 79 2e 20 7b 45 4e 44  mmediately. {END
13840 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  }.** </li>.** </
13850 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
13860 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
13870 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
13880 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
13890 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
138a0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
138b0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
138c0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
138d0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
138e0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
138f0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
13900 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
13910 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
13920 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
13930 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
13940 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
13950 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
13960 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
13970 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
13980 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
13990 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
139a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
139b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
139c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
139d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
139e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
139f0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
13a00 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
13a10 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
13a20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
13a30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
13a40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
13a50 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
13a60 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
13a70 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
13a80 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
13a90 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
13aa0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
13ab0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
13ac0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
13ad0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
13ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
13af0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
13b00 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
13b10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
13b20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
13b30 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
13b40 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
13b50 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
13b60 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
13b70 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
13b80 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
13b90 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
13ba0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
13bb0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
13bc0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
13bd0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
13be0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
13bf0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
13c00 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
13c10 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
13c20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
13c30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
13c40 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
13c50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
13c60 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
13c70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
13c80 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
13c90 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
13ca0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
13cb0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
13cc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
13cd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
13ce0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
13cf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
13d00 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
13d10 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
13d20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
13d30 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
13d40 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
13d50 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
13d60 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
13d70 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52  /*.** CAPIREF: R
13d80 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
13d90 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30 7d  ent SQL {F13100}
13da0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d 20  .**.** {F13101} 
13db0 49 66 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  If the compiled 
13dc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 70 61  SQL statement pa
13dd0 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d  ssed as an argum
13de0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
13df0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
13e00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13e10 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
13e20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
13e30 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  ()],.** then thi
13e40 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
13e50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13e60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
13e70 64 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 74  d string.** cont
13e80 61 69 6e 69 6e 67 20 61 20 63 6f 70 79 20 6f 66  aining a copy of
13e90 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51   the original SQ
13ea0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 7b 46 31  L statement. {F1
13eb0 33 31 30 32 7d 20 54 68 65 0a 2a 2a 20 70 6f 69  3102} The.** poi
13ec0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
13ed0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
13ee0 74 0a 2a 2a 20 69 73 20 64 65 6c 65 74 65 64 20  t.** is deleted 
13ef0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  using sqlite3_fi
13f00 6e 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 7b 46 31  nalize()..** {F1
13f10 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67  3103} The string
13f20 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
13f30 69 74 65 33 5f 73 71 6c 28 29 20 69 73 20 61 6c  ite3_sql() is al
13f40 77 61 79 73 20 55 54 46 38 20 65 76 65 6e 0a 2a  ways UTF8 even.*
13f50 2a 20 69 66 20 61 20 55 54 46 31 36 20 73 74 72  * if a UTF16 str
13f60 69 6e 67 20 77 61 73 20 6f 72 69 67 69 6e 61 6c  ing was original
13f70 6c 79 20 65 6e 74 65 72 65 64 20 75 73 69 6e 67  ly entered using
13f80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13f90 65 31 36 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  e16_v2()].** or 
13fa0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a  the equivalent..
13fb0 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 34 7d 20 49  **.** {F13104} I
13fc0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
13fd0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  was compiled usi
13fe0 6e 67 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ng either of the
13ff0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
14000 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
14010 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
14020 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
14030 29 5d 2c 20 74 68 69 73 0a 2a 2a 20 66 75 6e 63  )], this.** func
14040 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 4e 55 4c  tion returns NUL
14050 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  L..*/.const char
14060 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
14070 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
14080 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
14090 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c  REF:  Dynamicall
140a0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
140b0 6a 65 63 74 20 20 7b 46 31 35 30 30 30 7d 0a 2a  ject  {F15000}.*
140c0 2a 0a 2a 2a 20 7b 46 31 35 30 30 31 7d 20 53 51  *.** {F15001} SQ
140d0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
140e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
140f0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
14100 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
14110 61 74 20 61 72 65 20 6f 72 20 63 61 6e 20 62 65  at are or can be
14120 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
14130 61 62 61 73 65 20 74 61 62 6c 65 2e 20 7b 45 4e  abase table. {EN
14140 44 7d 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  D}.** SQLite use
14150 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
14160 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
14170 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a 20  it stores.  .** 
14180 7b 46 31 35 30 30 32 7d 20 56 61 6c 75 65 73 20  {F15002} Values 
14190 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
141a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
141b0 63 61 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74  can be.** be int
141c0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
141d0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
141e0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
141f0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 74 79 70 65 64 65   NULL..*/.typede
14200 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
14210 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
14220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 51  ** CAPI3REF:  SQ
14230 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
14240 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30  xt Object {F1600
14250 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  1}.**.** The con
14260 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
14270 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
14280 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
14290 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
142a0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
142b0 2e 20 20 7b 46 31 36 30 30 32 7d 20 41 20 70 6f  .  {F16002} A po
142c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
142d0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f  te3_context.** o
142e0 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 20  bject is always 
142f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14300 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  to application-d
14310 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
14320 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ions..*/.typedef
14330 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
14340 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
14350 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
14360 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69  CAPI3REF:  Bindi
14370 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
14380 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
14390 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13500}.**.** 
143a0 7b 46 31 33 35 30 31 7d 20 49 6e 20 74 68 65 20  {F13501} In the 
143b0 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75  SQL strings inpu
143c0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
143d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
143e0 69 74 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73 2c  its.** variants,
143f0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
14400 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 61   replace by a pa
14410 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a 2a  rameter in one.*
14420 2a 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73  * of these forms
14430 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
14440 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
14450 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
14460 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41  AAA.** <li>  @AA
14470 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  A.** <li>  $VVV.
14480 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
14490 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
144a0 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
144b0 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
144c0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
144d0 41 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e  AAA is an alphan
144e0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
144f0 72 20 61 6e 64 20 56 56 56 20 69 73 20 61 20 76  r and VVV is a v
14500 61 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63  ariable name acc
14510 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  ording.** to the
14520 20 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66   syntax rules of
14530 20 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d   the TCL program
14540 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 20 7b  ming language. {
14550 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 76 61 6c 75  END}.** The valu
14560 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  es of these para
14570 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
14580 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
14590 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63  ter names").** c
145a0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
145b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
145c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
145d0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
145e0 2a 20 7b 46 31 33 35 30 32 7d 20 54 68 65 20 66  * {F13502} The f
145f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
14600 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
14610 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
14620 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f  lways.** is a po
14630 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
14640 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
14650 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
14660 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
14670 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
14680 73 20 76 61 72 69 61 6e 74 73 2e 20 20 7b 46 31  s variants.  {F1
14690 33 35 30 33 7d 20 54 68 65 20 73 65 63 6f 6e 64  3503} The second
146a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
146b0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
146c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
146d0 20 73 65 74 2e 20 20 7b 46 31 33 35 30 34 7d 20   set.  {F13504} 
146e0 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72  The.** first par
146f0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
14700 64 65 78 20 6f 66 20 31 2e 20 20 7b 46 31 33 35  dex of 1.  {F135
14710 30 35 7d 20 57 68 65 6e 20 74 68 65 20 73 61 6d  05} When the sam
14720 65 20 6e 61 6d 65 64 0a 2a 2a 20 70 61 72 61 6d  e named.** param
14730 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
14740 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
14750 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
14760 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
14770 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
14780 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
14790 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 0a  st occurrence. .
147a0 2a 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20  ** {F13506} The 
147b0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
147c0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
147d0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
147e0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
147f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
14800 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20  _name()] API if 
14810 64 65 73 69 72 65 64 2e 20 20 7b 46 31 33 35 30  desired.  {F1350
14820 37 7d 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20  7} The index.** 
14830 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
14840 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
14850 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 7b 46  ue of NNN..** {F
14860 31 33 35 30 38 7d 20 54 68 65 20 4e 4e 4e 20 76  13508} The NNN v
14870 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
14880 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63  ween 1 and the c
14890 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70  ompile-time.** p
148a0 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f  arameter SQLITE_
148b0 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
148c0 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c  BER (default val
148d0 75 65 3a 20 39 39 39 29 2e 20 7b 45 4e 44 7d 0a  ue: 999). {END}.
148e0 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66 3d 22  ** See <a href="
148f0 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d  limits.html">lim
14900 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72  its.html</a> for
14910 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
14920 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  rmation..**.** {
14930 46 31 33 35 30 39 7d 20 54 68 65 20 74 68 69 72  F13509} The thir
14940 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
14950 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
14960 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
14970 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
14980 31 33 35 31 30 7d 20 49 6e 20 74 68 6f 73 65 0a  13510} In those.
14990 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
149a0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
149b0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
149c0 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ue is the number
149d0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20   of bytes.** in 
149e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
149f0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
14a00 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
14a10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
14a20 20 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20   the.** string, 
14a30 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
14a40 66 20 63 68 61 72 61 63 74 65 72 73 2e 20 7b 46  f characters. {F
14a50 31 33 35 31 31 7d 20 20 54 68 65 20 6e 75 6d 62  13511}  The numb
14a60 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64  er.** of bytes d
14a70 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
14a80 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
14a90 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f  tor at the end o
14aa0 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 7b 46  f strings..** {F
14ab0 31 33 35 31 32 7d 0a 2a 2a 20 49 66 20 74 68 65  13512}.** If the
14ac0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14ad0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
14ae0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
14af0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75   string is.** nu
14b00 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
14b10 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
14b20 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 7b  ro terminator. {
14b30 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  END}.**.** {F135
14b40 31 33 7d 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  13}.** The fifth
14b50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
14b60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
14b70 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
14b80 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
14b90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
14ba0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
14bb0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
14bc0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
14bd0 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66 74 65 72  or.** text after
14be0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
14bf0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 7b 46  shed with it. {F
14c00 31 33 35 31 34 7d 20 49 66 20 74 68 65 20 66 69  13514} If the fi
14c10 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
14c20 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
14c30 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
14c40 54 49 43 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c  TIC], then the l
14c50 69 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 74  ibrary assumes t
14c60 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
14c70 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
14c80 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
14c90 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
14ca0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
14cb0 65 64 2e 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20  ed..** {F13515} 
14cc0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
14cd0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
14ce0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
14cf0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
14d00 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
14d10 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
14d20 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
14d30 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
14d40 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
14d50 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
14d60 65 20 72 65 74 75 72 6e 73 2e 20 7b 45 4e 44 7d  e returns. {END}
14d70 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 30 7d 20  .**.** {F13520} 
14d80 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
14d90 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
14da0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
14db0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
14dc0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
14dd0 69 74 68 20 7a 65 72 6f 73 2e 20 20 7b 46 31 33  ith zeros.  {F13
14de0 35 32 31 7d 20 41 20 7a 65 72 6f 62 6c 6f 62 20  521} A zeroblob 
14df0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
14e00 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
14e10 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
14e20 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a  r to hold it siz
14e30 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
14e40 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 20  eing processed. 
14e50 7b 45 4e 44 7d 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  {END}.** Zeroblo
14e60 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
14e70 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
14e80 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  e-holders for BL
14e90 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
14ea0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
14eb0 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20  itten using .** 
14ec0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
14ed0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42  en | increment B
14ee0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
14ef0 73 2e 20 7b 46 31 33 35 32 32 7d 20 41 20 6e 65  s. {F13522} A ne
14f00 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20  gative.** value 
14f10 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
14f20 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
14f30 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 20  ro-length BLOB. 
14f40 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  {END}.**.** {F13
14f50 35 33 30 7d 20 54 68 65 20 73 71 6c 69 74 65 33  530} The sqlite3
14f60 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
14f70 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
14f80 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
14f90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14fa0 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
14fb0 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
14fc0 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
14fd0 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
14fe0 5f 73 74 65 70 28 29 5d 2e 20 7b 46 31 33 35 33  _step()]. {F1353
14ff0 31 7d 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61  1}.** Bindings a
15000 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
15010 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
15020 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
15030 0a 2a 2a 20 7b 46 31 33 35 33 32 7d 20 55 6e 62  .** {F13532} Unb
15040 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
15050 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
15060 61 73 20 4e 55 4c 4c 2e 20 7b 45 4e 44 7d 0a 2a  as NULL. {END}.*
15070 2a 0a 2a 2a 20 7b 46 31 33 35 34 30 7d 20 54 68  *.** {F13540} Th
15080 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
15090 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
150a0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
150b0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
150c0 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
150d0 77 72 6f 6e 67 2e 20 20 7b 46 31 33 35 34 31 7d  wrong.  {F13541}
150e0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
150f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
15100 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
15110 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
15120 72 61 6e 67 65 2e 20 20 7b 46 31 33 35 34 32 7d  range.  {F13542}
15130 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
15140 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
15150 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20  alloc fails..** 
15160 7b 46 31 33 35 34 33 7d 20 5b 53 51 4c 49 54 45  {F13543} [SQLITE
15170 5f 4d 49 53 55 53 45 5d 20 69 73 20 72 65 74 75  _MISUSE] is retu
15180 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
15190 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
151a0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
151b0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
151c0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
151d0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
151e0 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
151f0 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  lized..*/.int sq
15200 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
15210 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
15220 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
15230 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
15240 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
15250 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
15260 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
15270 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
15280 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
15290 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
152a0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
152b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
152c0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
152d0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
152e0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
152f0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
15300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
15310 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
15320 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
15330 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
15340 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
15350 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
15360 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
15370 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
15380 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
15390 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
153a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
153b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
153c0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
153d0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
153e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
153f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
15400 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
15410 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
15420 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
15430 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
15440 20 4f 66 20 48 6f 73 74 20 50 61 72 61 6d 65 74   Of Host Paramet
15450 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a  ers {F13600}.**.
15460 2a 2a 20 7b 46 31 33 36 30 31 7d 20 52 65 74 75  ** {F13601} Retu
15470 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 68  rn the largest h
15480 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 6e  ost parameter in
15490 64 65 78 20 69 6e 20 74 68 65 20 70 72 65 63 6f  dex in the preco
154a0 6d 70 69 6c 65 64 0a 2a 2a 20 73 74 61 74 65 6d  mpiled.** statem
154b0 65 6e 74 20 67 69 76 65 6e 20 61 73 20 74 68 65  ent given as the
154c0 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 33 36   argument. {F136
154d0 30 32 7d 20 57 68 65 6e 20 74 68 65 20 68 6f 73  02} When the hos
154e0 74 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  t parameters.** 
154f0 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  are of the forms
15500 20 6c 69 6b 65 20 22 3a 41 41 41 22 2c 20 22 24   like ":AAA", "$
15510 56 56 56 22 2c 20 22 40 41 41 41 22 2c 20 6f 72  VVV", "@AAA", or
15520 20 22 3f 22 2c 0a 2a 2a 20 74 68 65 6e 20 74 68   "?",.** then th
15530 65 79 20 61 72 65 20 61 73 73 69 67 6e 65 64 20  ey are assigned 
15540 73 65 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 65  sequential incre
15550 61 73 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 65  asing numbers be
15560 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20  ginning.** with 
15570 6f 6e 65 2c 20 73 6f 20 74 68 65 20 76 61 6c 75  one, so the valu
15580 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
15590 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  e number of para
155a0 6d 65 74 65 72 73 2e 0a 2a 2a 20 7b 46 31 33 36  meters..** {F136
155b0 30 33 7d 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69  03} However.** i
155c0 66 20 74 68 65 20 73 61 6d 65 20 68 6f 73 74 20  f the same host 
155d0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 20 69  parameter name i
155e0 73 20 75 73 65 64 20 6d 75 6c 74 69 70 6c 65 20  s used multiple 
155f0 74 69 6d 65 73 2c 20 65 61 63 68 20 6f 63 63 75  times, each occu
15600 72 72 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76  rrance.** is giv
15610 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62  en the same numb
15620 65 72 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65  er, so the value
15630 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 61   returned in tha
15640 74 20 63 61 73 65 20 69 73 20 74 68 65 20 6e 75  t case is the nu
15650 6d 62 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75  mber.** of uniqu
15660 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  e host parameter
15670 20 6e 61 6d 65 73 2e 20 7b 46 31 33 36 30 34 7d   names. {F13604}
15680 20 49 66 20 68 6f 73 74 20 70 61 72 61 6d 65 74   If host paramet
15690 65 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ers of the.** fo
156a0 72 6d 20 22 3f 4e 4e 4e 22 20 61 72 65 20 75 73  rm "?NNN" are us
156b0 65 64 20 28 77 68 65 72 65 20 4e 4e 4e 20 69 73  ed (where NNN is
156c0 20 61 6e 20 69 6e 74 65 67 65 72 29 20 74 68 65   an integer) the
156d0 6e 20 74 68 65 72 65 20 6d 69 67 68 74 20 62 65  n there might be
156e0 0a 2a 2a 20 67 61 70 73 20 69 6e 20 74 68 65 20  .** gaps in the 
156f0 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64 20 74 68  numbering and th
15700 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15710 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
15720 63 65 20 69 73 0a 2a 2a 20 74 68 65 20 69 6e 64  ce is.** the ind
15730 65 78 20 6f 66 20 74 68 65 20 68 6f 73 74 20 70  ex of the host p
15740 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68  arameter with th
15750 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
15760 76 61 6c 75 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  value. {END}.**.
15770 2a 2a 20 7b 55 31 33 36 30 35 7d 20 54 68 65 20  ** {U13605} The 
15780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
15790 6e 74 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 5b  nt must not be [
157a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
157b0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a   | finalized].**
157c0 20 70 72 69 6f 72 20 74 6f 20 74 68 69 73 20 72   prior to this r
157d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 69 6e 67  outine returning
157e0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74 68 65  .  Otherwise the
157f0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
15800 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72  efined.** and pr
15810 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
15820 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
15830 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
15840 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
15850 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
15860 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
15870 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
15880 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a  r {F13620}.**.**
15890 20 7b 46 31 33 36 32 31 7d 20 54 68 69 73 20 72   {F13621} This r
158a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
158b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
158c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
158d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 6e  .** parameter in
158e0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
158f0 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
15900 65 6d 65 6e 74 5d 2e 20 7b 46 31 33 36 32 32 7d  ement]. {F13622}
15910 0a 2a 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74  .** Host paramet
15920 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
15930 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
15940 20 6f 72 20 22 24 56 56 56 22 20 68 61 76 65 20   or "$VVV" have 
15950 61 20 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20  a name.** which 
15960 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a  is the string ":
15970 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
15980 72 20 22 24 56 56 56 22 2e 20 0a 2a 2a 20 49 6e  r "$VVV". .** In
15990 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
159a0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
159b0 20 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69   "$" or "@".** i
159c0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
159d0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 20  rt of the name. 
159e0 20 7b 46 31 33 36 32 36 7d 0a 2a 2a 20 50 61 72   {F13626}.** Par
159f0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
15a00 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e  orm "?" or "?NNN
15a10 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a  " have no name..
15a20 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 33 7d 20 54  **.** {F13623} T
15a30 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
15a40 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
15a50 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
15a60 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 34 7d  ..**.** {F13624}
15a70 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20   If the value n 
15a80 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
15a90 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70  or if the n-th p
15aa0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
15ab0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
15ac0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
15ad0 20 7b 46 31 33 36 32 35 7d 20 54 68 65 20 72 65   {F13625} The re
15ae0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
15af0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 68  .** always in th
15b00 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
15b10 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
15b20 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
15b30 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
15b40 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
15b50 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
15b60 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
15b70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
15b80 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
15b90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
15ba0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
15bb0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
15bc0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
15bd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
15be0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
15bf0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
15c00 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a  ame {F13640}.**.
15c10 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 69 73  ** {F13641} This
15c20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15c30 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 20   the index of a 
15c40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77  host parameter w
15c50 69 74 68 20 74 68 65 0a 2a 2a 20 67 69 76 65 6e  ith the.** given
15c60 20 6e 61 6d 65 2e 20 20 7b 46 31 33 36 34 32 7d   name.  {F13642}
15c70 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 20 6d   The name must m
15c80 61 74 63 68 20 65 78 61 63 74 6c 79 2e 20 20 7b  atch exactly.  {
15c90 46 31 33 36 34 33 7d 0a 2a 2a 20 49 66 20 6e 6f  F13643}.** If no
15ca0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
15cb0 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69  the given name i
15cc0 73 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20  s found, return 
15cd0 30 2e 0a 2a 2a 20 7b 46 31 33 36 34 34 7d 20 50  0..** {F13644} P
15ce0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 20 6d  arameter names m
15cf0 75 73 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f 0a  ust be UTF8..*/.
15d00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
15d10 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
15d20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
15d30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
15d40 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
15d50 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
15d60 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
15d70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
15d80 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F13660}.**.** {
15d90 46 31 33 36 36 31 7d 20 43 6f 6e 74 72 61 72 79  F13661} Contrary
15da0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
15db0 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
15dc0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
15dd0 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74  s not.** reset t
15de0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
15df0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
15e00 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69  ] on a .** [sqli
15e10 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
15e20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
15e30 7b 46 31 33 36 36 32 7d 20 55 73 65 20 74 68 69  {F13662} Use thi
15e40 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20  s routine to.** 
15e50 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
15e60 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
15e70 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
15e80 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
15e90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
15ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15eb0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
15ec0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
15ed0 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a  Set {F13710}.**.
15ee0 2a 2a 20 7b 46 31 33 37 31 31 7d 20 52 65 74 75  ** {F13711} Retu
15ef0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
15f00 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
15f10 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
15f20 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b  ned by the .** [
15f30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63  sqlite3_stmt | c
15f40 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
15f50 65 6d 65 6e 74 5d 2e 20 7b 46 31 33 37 31 32 7d  ement]. {F13712}
15f60 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
15f70 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53  turns 0.** if pS
15f80 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74  tmt is an SQL st
15f90 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
15fa0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
15fb0 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70  a (for .** examp
15fc0 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a  le an UPDATE)..*
15fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
15fe0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
15ff0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
16000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16010 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
16020 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
16030 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F13720}.**.** {F
16040 31 33 37 32 31 7d 20 54 68 65 73 65 20 72 6f 75  13721} These rou
16050 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
16060 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
16070 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
16080 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
16090 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
160a0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
160b0 2e 20 20 7b 46 31 33 37 32 32 7d 20 54 68 65 20  .  {F13722} The 
160c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
160d0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
160e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
160f0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
16100 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73  erminated UTF8 s
16110 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
16120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
16130 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
16140 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
16150 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
16160 54 46 31 36 20 73 74 72 69 6e 67 2e 20 7b 46 31  TF16 string. {F1
16170 33 37 32 33 7d 20 20 54 68 65 20 66 69 72 73 74  3723}  The first
16180 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
16190 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  e.** [sqlite3_st
161a0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
161b0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d  atement] that im
161c0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53 45 4c  plements the SEL
161d0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  ECT statement..*
161e0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
161f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63 6f  ameter is the co
16200 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68  lumn number.  Th
16210 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
16220 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20  mn is.** number 
16230 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34  0..**.** {F13724
16240 7d 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  } The returned s
16250 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
16260 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
16270 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  her the .** [sql
16280 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
16290 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
162a0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
162b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
162c0 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c  e()].** or until
162d0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73   the next call s
162e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
162f0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
16300 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a  column_name16().
16310 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  ** on the same c
16320 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  olumn..**.** {F1
16330 33 37 32 35 7d 20 49 66 20 73 71 6c 69 74 65 33  3725} If sqlite3
16340 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
16350 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
16360 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
16370 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
16380 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
16390 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
163a0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
163b0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
163c0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
163d0 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  rned..*/.const c
163e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
163f0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
16400 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
16410 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
16420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
16430 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
16440 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
16450 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
16460 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
16470 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37  ery Result {F137
16480 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34  40}.**.** {F1374
16490 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  1} These routine
164a0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
164b0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77  s to determine w
164c0 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68  hat column of wh
164d0 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77  at.** table in w
164e0 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20  hich database a 
164f0 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45  result of a SELE
16500 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  CT statement com
16510 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 7b 46 31 33  es from..** {F13
16520 37 34 32 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66  742} The name of
16530 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
16540 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
16550 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
16560 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
16570 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74  UTF8 or UTF16 st
16580 72 69 6e 67 2e 20 20 7b 46 31 33 37 34 33 7d 20  ring.  {F13743} 
16590 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
165a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
165b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
165c0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
165d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
165e0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
165f0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
16600 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
16610 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
16620 61 6d 65 2e 20 7b 46 31 33 37 34 34 7d 0a 2a 2a  ame. {F13744}.**
16630 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
16640 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
16650 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  til.** the [sqli
16660 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
16670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
16680 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e  s destroyed usin
16690 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  g.** [sqlite3_fi
166a0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
166b0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
166c0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
166d0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
166e0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
166f0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  oding..**.** {F1
16700 33 37 34 35 7d 20 54 68 65 20 6e 61 6d 65 73 20  3745} The names 
16710 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
16720 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
16730 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
16740 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
16750 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
16760 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 36 7d  ..**.** {F13746}
16770 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16780 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
16790 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
167a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
167b0 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
167c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
167d0 7b 46 31 33 37 34 37 7d 20 54 68 65 73 65 20 66  {F13747} These f
167e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
167f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
16800 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
16810 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
16820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
16830 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
16840 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
16850 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  rgument..**.** {
16860 46 31 33 37 34 38 7d 20 49 66 20 74 68 65 20 4e  F13748} If the N
16870 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
16880 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
16890 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
168a0 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75  sion.** or subqu
168b0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
168c0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
168d0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
168e0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
168f0 74 75 72 6e 20 4e 55 4c 4c 2e 20 20 7b 46 31 33  turn NULL.  {F13
16900 37 34 39 7d 20 4f 74 68 65 72 77 69 73 65 2c 20  749} Otherwise, 
16910 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
16920 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
16930 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
16940 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  e, table and col
16950 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
16960 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
16970 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
16980 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 35  om..**.** {F1375
16990 30 7d 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  0} As with all o
169a0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
169b0 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65  , those postfixe
169c0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
169d0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
169e0 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68  oded strings, th
169f0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
16a00 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20  s return UTF-8. 
16a10 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
16a20 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
16a30 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
16a40 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
16a50 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 0a  piled with the .
16a60 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
16a70 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
16a80 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
16a90 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
16aa0 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20  .** {U13751}.** 
16ab0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
16ac0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
16ad0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
16ae0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
16af0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
16b00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
16b10 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
16b20 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
16b30 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
16b40 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
16b50 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
16b60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
16b70 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
16b80 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
16b90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
16ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
16bb0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
16bc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
16bd0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
16be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
16bf0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
16c00 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
16c10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
16c20 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
16c30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
16c40 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
16c50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
16c60 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
16c70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
16c80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
16c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
16ca0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
16cb0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
16cc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
16cd0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
16ce0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
16cf0 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a  t {F13760}.**.**
16d00 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
16d10 65 74 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74  eter is a [sqlit
16d20 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
16d30 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
16d40 5d 2e 20 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20  ]. .** {F13761} 
16d50 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
16d60 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73 74  t is a SELECT st
16d70 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
16d80 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
16d90 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  e .** returned r
16da0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
16db0 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74 61  t SELECT is a ta
16dc0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
16dd0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
16de0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
16df0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
16e00 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
16e10 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
16e20 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 33 37 36  eturned.  {F1376
16e30 32 7d 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  2} If the Nth co
16e40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
16e50 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
16e60 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
16e70 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
16e80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
16e90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 7b 46 31 33  eturned..** {F13
16ea0 37 36 33 7d 20 54 68 65 20 72 65 74 75 72 6e 65  763} The returne
16eb0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
16ec0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
16ed0 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f 72  .  {END} .** For
16ee0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65   example, in the
16ef0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
16f00 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
16f10 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
16f20 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74  NT);.**.** And t
16f30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
16f40 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a  tement compiled:
16f50 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
16f60 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
16f70 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69  ;.**.** Then thi
16f80 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
16f90 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
16fa0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
16fb0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65  the second.** re
16fc0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
16fd0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
16fe0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
16ff0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
17000 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a  mn.** (i==0)..**
17010 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
17020 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
17030 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73   typing.  So jus
17040 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
17050 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
17060 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
17070 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
17080 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
17090 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
170a0 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
170b0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
170c0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
170d0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
170e0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
170f0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
17100 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
17110 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73    Type.** is ass
17120 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
17130 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
17140 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
17150 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
17160 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
17170 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
17180 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
17190 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
171a0 69 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74  ite3_stmt *, int
171b0 20 69 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   i);.const void 
171c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
171d0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
171e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
171f0 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  /* .** CAPI3REF:
17200 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51    Evaluate An SQ
17210 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  L Statement {F13
17220 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  200}.**.** After
17230 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
17240 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
17250 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
17260 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c  ared with a call
17270 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73  .** to either [s
17280 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17290 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
172a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
172b0 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a   or to one of.**
172c0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
172d0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
172e0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
172f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
17300 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  ()],.** then thi
17310 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  s function must 
17320 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
17330 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
17340 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20  valuate the .** 
17350 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
17360 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
17370 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
17380 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65  this sqlite3_ste
17390 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
173a0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
173b0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
173c0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
173d0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
173e0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
173f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17400 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
17410 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
17420 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
17430 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
17440 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
17450 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
17460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
17470 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
17480 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
17490 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
174a0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
174b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
174c0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
174d0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
174e0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
174f0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
17500 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74  n the lagacy int
17510 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
17520 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
17530 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
17540 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49  BUSY], .** [SQLI
17550 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
17560 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
17570 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
17580 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
17590 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
175a0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
175b0 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  he other [SQLITE
175c0 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
175d0 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  e].** or [SQLITE
175e0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
175f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
17600 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  de] might be ret
17610 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c  urned as.** well
17620 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
17630 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
17640 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
17650 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
17660 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
17670 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
17680 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
17690 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
176a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
176b0 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
176c0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
176d0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
176e0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
176f0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
17700 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
17710 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
17720 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
17730 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
17740 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
17750 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
17760 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
17770 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
17780 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
17790 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
177a0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
177b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
177c0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
177d0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
177e0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
177f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
17800 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
17810 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
17820 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
17830 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
17840 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
17850 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
17860 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
17870 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
17880 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
17890 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
178a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
178b0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
178c0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
178d0 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51  ta, then .** [SQ
178e0 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74  LITE_ROW] is ret
178f0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
17900 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
17910 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f  a is ready.** fo
17920 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
17930 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  the caller. The 
17940 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
17950 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  cessed using.** 
17960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
17970 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e  umn_int | column
17980 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
17990 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
179a0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
179b0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
179c0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
179d0 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b  f data..** .** [
179e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
179f0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
17a00 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
17a10 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
17a20 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
17a30 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
17a40 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
17a50 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
17a60 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
17a70 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
17a80 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
17a90 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
17aa0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
17ab0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
17ac0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
17ad0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
17ae0 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d  error code (exam
17af0 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple:.** [SQLITE_
17b00 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
17b10 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
17b20 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
17b30 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
17b40 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
17b50 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
17b60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
17b70 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17b80 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
17b90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
17ba0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
17bb0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
17bc0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
17bd0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
17be0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
17bf0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
17c00 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
17c10 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
17c20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
17c30 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
17c40 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
17c50 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
17c60 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33  ed on a [sqlite3
17c70 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
17c80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
17c90 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
17ca0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
17cb0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
17cc0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
17cd0 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69  at had .** previ
17ce0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
17cf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
17d00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
17d10 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
17d20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
17d30 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
17d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
17d50 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
17d60 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
17d70 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
17d80 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
17d90 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
17da0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
17db0 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20  :</b>.** In the 
17dc0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
17dd0 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  , .** the sqlite
17de0 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77  3_step() API alw
17df0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
17e00 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
17e10 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
17e20 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
17e30 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ny error other t
17e40 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
17e50 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
17e60 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
17e70 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  ust call [sqlite
17e80 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
17e90 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
17ea0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
17eb0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
17ec0 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53  e specific.** [S
17ed0 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
17ee0 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74  sult codes] that
17ef0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
17f00 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
17f10 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
17f20 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
17f30 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
17f40 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
17f50 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
17f60 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
17f70 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
17f80 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
17f90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
17fa0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
17fb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17fc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
17fd0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
17fe0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
17ff0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
18000 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
18010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
18020 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a  )], then the .**
18030 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
18040 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
18050 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
18060 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
18070 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
18080 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
18090 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
180a0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
180b0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
180c0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
180d0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
180e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
180f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
18100 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
18110 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13770}.**.** Re
18120 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
18130 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
18140 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
18150 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
18160 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 41  **.** {F13771} A
18170 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b  fter a call to [
18180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18190 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51  that returns [SQ
181a0 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 74 68  LITE_ROW],.** th
181b0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69  is routine.** wi
181c0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ll return the sa
181d0 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65 20  me value as the 
181e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
181f0 63 6f 75 6e 74 28 29 5d 20 66 75 6e 63 74 69 6f  count()] functio
18200 6e 2e 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 0a 2a  n..** {F13772}.*
18210 2a 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33  * After [sqlite3
18220 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
18230 75 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49 54 45  urned an [SQLITE
18240 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
18250 42 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b  BUSY], or.** a [
18260 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
18270 72 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62  rror code], or b
18280 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
18290 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
182a0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  .** called on th
182b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  e [sqlite3_stmt 
182c0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
182d0 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69  ment] for the fi
182e0 72 73 74 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69  rst time,.** thi
182f0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
18300 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  s zero..*/.int s
18310 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
18320 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
18330 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
18340 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
18350 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b  ntal Datatypes {
18360 46 31 30 32 36 35 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F10265}.**.** {F
18370 31 30 32 36 36 7d 45 76 65 72 79 20 76 61 6c 75  10266}Every valu
18380 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
18390 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
183a0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
183b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
183c0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
183d0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
183e0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
183f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
18400 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
18410 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
18420 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
18430 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
18440 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
18450 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
18460 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
18470 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
18480 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
18490 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
184a0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
184b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
184c0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
184d0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
184e0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
184f0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
18500 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
18510 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
18520 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
18530 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
18540 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a  QLITE3_TEXT not.
18550 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
18560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18570 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
18580 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
18590 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
185a0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
185b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
185c0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
185d0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
185e0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
185f0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
18600 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
18610 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
18620 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
18630 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
18640 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61  3REF: Results Va
18650 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
18660 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a 2a 2a  y {F13800}.**.**
18670 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18680 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
18690 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69  on about.** a si
186a0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
186b0 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c  he current resul
186c0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
186d0 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63  .  In every.** c
186e0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
186f0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
18700 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b  ter to the .** [
18710 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
18720 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  QL statement] th
18730 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65  at is being.** e
18740 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
18750 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68  qlite3_stmt*] th
18760 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
18770 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
18780 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
18790 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
187a0 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74  riants) and.** t
187b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
187c0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
187d0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
187e0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
187f0 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ion .** should b
18800 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  e returned.  The
18810 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
18820 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
18830 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e  set.** has an in
18840 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20  dex of 0..**.** 
18850 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
18860 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75 72 72  ment is not curr
18870 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
18880 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
18890 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c  f the.** the col
188a0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
188b0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
188c0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
188d0 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ed. .** These ro
188e0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
188f0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
18900 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
18910 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
18920 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
18930 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
18940 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
18950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
18960 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
18970 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
18980 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73 75 62  as been call sub
18990 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
189a0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
189b0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
189c0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
189d0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
189e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
189f0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
18a00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
18a10 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
18a20 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
18a30 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
18a40 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
18a50 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
18a60 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
18a70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
18a80 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
18a90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
18aa0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
18ab0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
18ac0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
18ad0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
18ae0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
18af0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
18b00 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
18b10 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d.  .**.** The s
18b20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
18b30 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
18b40 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
18b50 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
18b60 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
18b70 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
18b80 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
18b90 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68  sult column.  Th
18ba0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
18bb0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
18bc0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
18bd0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
18be0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
18bf0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
18c00 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
18c10 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
18c20 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
18c30 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
18c40 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
18c50 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
18c60 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
18c70 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
18c80 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
18c90 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
18ca0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
18cb0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18cc0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
18cd0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
18ce0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
18cf0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
18d00 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
18d10 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
18d20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
18d30 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
18d40 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
18d50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
18d60 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
18d70 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
18d80 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
18d90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
18da0 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  () .** routine r
18db0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
18dc0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
18dd0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
18de0 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  g..** If the res
18df0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
18e00 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
18e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
18e20 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
18e30 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
18e40 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
18e50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
18e60 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20  of bytes..** If 
18e70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
18e80 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
18e90 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
18ea0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
18eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
18ec0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
18ed0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
18ee0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
18ef0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
18f00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
18f10 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
18f20 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
18f30 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
18f40 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
18f50 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
18f60 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
18f70 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63  e string.  For c
18f80 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
18f90 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
18fa0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
18fb0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
18fc0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
18fd0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
18fe0 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20  ..**.** Strings 
18ff0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
19000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
19010 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
19020 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
19030 2a 20 65 76 65 6e 20 7a 65 72 6f 2d 6c 65 6e 67  * even zero-leng
19040 74 68 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  th strings, are 
19050 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
19060 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74  inated.  The ret
19070 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
19080 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
19090 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
190a0 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69  ro-length blob i
190b0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
190c0 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
190d0 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
190e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
190f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
19100 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
19110 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
19120 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
19130 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
19140 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
19150 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74  t in UTF-16 inst
19160 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a  ead of UTF-8.  .
19170 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** The zero term
19180 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
19190 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
191a0 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ount..**.** Thes
191b0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
191c0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
191d0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
191e0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
191f0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
19200 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
19210 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
19220 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
19230 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
19240 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
19250 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
19260 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
19270 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73  o do the convers
19280 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ion.** automatic
19290 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  ally.  The follo
192a0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
192b0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
192c0 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61  ns that.** are a
192d0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
192e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
192f0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
19300 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
19310 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
19320 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
19330 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
19340 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
19350 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
19360 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
19370 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
19380 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
19390 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
193a0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
193b0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
193c0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
193d0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
193e0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
193f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
19400 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
19410 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
19420 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
19430 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
19440 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
19450 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
19460 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
19470 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
19480 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
19490 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
194a0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
194b0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
194c0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
194d0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
194e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
194f0 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52  e as for INTEGER
19500 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
19510 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
19520 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
19530 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
19540 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
19550 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
19560 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
19570 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
19580 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
19590 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
195a0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
195b0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
195c0 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
195d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
195e0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
195f0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
19600 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
19610 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
19620 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
19630 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
19640 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
19650 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
19660 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
19670 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
19680 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
19690 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
196a0 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
196b0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
196c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
196d0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
196e0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
196f0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
19700 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
19710 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
19720 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
19730 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
19740 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
19750 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
19760 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  te>.**.** The ta
19770 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
19780 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
19790 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
197a0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
197b0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
197c0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
197d0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
197e0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
197f0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65   has its.** on e
19800 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quavalent intern
19810 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
19820 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
19830 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
19840 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
19850 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
19860 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
19870 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
19880 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
19890 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
198a0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
198b0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
198c0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
198d0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
198e0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
198f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
19900 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
19910 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
19920 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
19930 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
19940 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a  e invalidated. .
19950 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
19960 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
19970 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
19980 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
19990 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
199a0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
199b0 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
199c0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
199d0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
199e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
199f0 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  t() .**         
19a00 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
19a10 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
19a20 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
19a30 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
19a40 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65 64  **          need
19a50 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
19a60 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c  the string.</p><
19a70 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c  /li>.**.** <li><
19a80 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
19a90 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
19aa0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
19ab0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
19ac0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  () or.**        
19ad0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
19ae0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
19af0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
19b00 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
19b10 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
19b20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f  to UTF-16.</p></
19b30 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70  li>.**.** <li><p
19b40 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  >  The initial c
19b50 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
19b60 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
19b70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
19b80 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
19b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
19ba0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
19bb0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
19bc0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
19bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 55  **          to U
19be0 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a  TF-8.</p></li>.*
19bf0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f  * </ul>.**.** Co
19c00 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
19c10 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
19c20 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
19c30 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
19c40 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
19c50 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
19c60 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
19c70 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
19c80 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
19c90 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
19ca0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
19cb0 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68  points to will h
19cc0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
19cd0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
19ce0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
19cf0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
19d00 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
19d10 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
19d20 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f  time it is.** no
19d30 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
19d40 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
19d50 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
19d60 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a   invalidated.  .
19d70 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
19d80 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
19d90 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
19da0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
19db0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
19dc0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
19dd0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
19de0 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  **  <ul>.**  <li
19df0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
19e00 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
19e10 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
19e20 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
19e30 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
19e40 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
19e50 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
19e60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
19e70 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
19e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
19e90 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
19ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
19eb0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
19ec0 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  *  </ul>.**.** I
19ed0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
19ee0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
19ef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
19f00 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  xt(), sqlite3_co
19f10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  lumn_blob(),.** 
19f20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
19f30 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
19f40 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
19f50 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65  sult into the de
19f60 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c  sired.** format,
19f70 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
19f80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
19f90 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  s() or sqlite3_c
19fa0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
19fb0 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73  to.** find the s
19fc0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
19fd0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
19fe0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
19ff0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
1a000 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
1a010 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
1a020 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
1a030 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e  olumn_bytes16().
1a040 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20    And do not.** 
1a050 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
1a060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1a070 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  16() with calls 
1a080 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
1a090 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
1a0a0 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   The pointers re
1a0b0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
1a0c0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
1a0d0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
1a0e0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
1a0f0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
1a100 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a110 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
1a120 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
1a130 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1a140 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
1a150 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
1a160 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
1a170 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20  gs.** and blobs 
1a180 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
1a190 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
1a1a0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
1a1b0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
1a1c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
1a1d0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
1a1e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1a1f0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
1a200 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72   .** [sqlite3_fr
1a210 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ee()]..**.** If 
1a220 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1a230 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
1a240 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
1a250 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
1a260 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1a270 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
1a280 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
1a290 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
1a2a0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
1a2b0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
1a2c0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
1a2d0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
1a2e0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
1a2f0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
1a300 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1a310 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
1a320 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
1a330 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a  LITE_NOMEM]..*/.
1a340 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1a350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
1a360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1a370 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
1a380 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
1a390 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
1a3a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
1a3b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1a3c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
1a3d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
1a3e0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
1a3f0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
1a400 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1a410 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
1a420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
1a430 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1a440 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
1a450 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1a460 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
1a470 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1a480 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
1a490 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
1a4a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1a4b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1a4c0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
1a4d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1a4e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
1a4f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
1a500 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
1a510 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
1a520 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1a530 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
1a540 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
1a550 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
1a560 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
1a570 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
1a580 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
1a590 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1a5a0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33  ent Object {F133
1a5b0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
1a5c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1a5d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
1a5e0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
1a5f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
1a600 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
1a610 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20   statement]. If 
1a620 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
1a630 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75  s.** executed su
1a640 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e  ccessfully, or n
1a650 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
1a660 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ll, then SQLITE_
1a670 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
1a680 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  ** If execution 
1a690 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
1a6a0 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20   failed then an 
1a6b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
1a6c0 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  R | error code] 
1a6d0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1a6e0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
1a6f0 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20   error code].** 
1a700 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a  is returned. .**
1a710 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1a720 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
1a730 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
1a740 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1a750 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1a760 74 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74 75  te3_stmt | virtu
1a770 61 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66  al machine].  If
1a780 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
1a790 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  hine has not .**
1a7a0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
1a7b0 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
1a7c0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
1a7d0 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
1a7e0 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
1a7f0 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e  n error or an in
1a800 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b  terrupt.  (See [
1a810 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a820 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d  t()].) .** Incom
1a830 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
1a840 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
1a850 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
1a860 73 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a  s cancelled,  .*
1a870 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
1a880 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
1a890 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53  , and the .** [S
1a8a0 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
1a8b0 73 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75 72  sult code] retur
1a8c0 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
1a8d0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69  ITE_ABORT]..*/.i
1a8e0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
1a8f0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
1a900 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1a910 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
1a920 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
1a930 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
1a940 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3330}.**.** The 
1a950 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
1a960 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
1a970 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a  ed to reset a .*
1a980 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
1a990 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  | compiled SQL s
1a9a0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
1a9b0 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 27  ..** back to it'
1a9c0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
1a9d0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
1a9e0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
1a9f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
1aa00 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
1aa10 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
1aa20 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
1aa30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
1aa40 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
1aa50 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
1aa60 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
1aa70 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
1aa80 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1aa90 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
1aaa0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a  he bindings..*/.
1aab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
1aac0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
1aad0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1aae0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
1aaf0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
1ab00 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 31 30  Functions {F1610
1ab10 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  0}.**.** The fol
1ab20 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
1ab30 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
1ab40 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
1ab50 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
1ab60 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69  .** or to redefi
1ab70 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ne the behavior 
1ab80 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
1ab90 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
1aba0 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a  regates.  The.**
1abb0 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79   difference only
1abc0 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f   between the two
1abd0 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
1abe0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
1abf0 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
1ac00 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
1ac10 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
1ac20 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
1ac30 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1ac40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1ac50 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
1ac60 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  6 for sqlite3_cr
1ac70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
1ac80 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
1ac90 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
1aca0 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20 64 61  he [sqlite3 | da
1acb0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 74  tabase handle] t
1acc0 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a  hat holds the.**
1acd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
1ace0 20 61 67 67 72 65 67 61 74 65 20 69 73 20 74 6f   aggregate is to
1acf0 20 62 65 20 61 64 64 65 64 20 6f 72 20 72 65 64   be added or red
1ad00 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e  efined. If a sin
1ad10 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  gle.** program u
1ad20 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
1ad30 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
1ad40 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  e internally, th
1ad50 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  en SQL.** functi
1ad60 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
1ad70 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
1ad80 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20  individually to 
1ad90 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a  each database.**
1ada0 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69   handle with whi
1adb0 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20  ch they will be 
1adc0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
1add0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ade0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1adf0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1ae00 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a   to be created.*
1ae10 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a  * or redefined..
1ae20 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** The length of
1ae30 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
1ae40 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
1ae50 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  s, exclusive of 
1ae60 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72  the .** zero-ter
1ae70 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
1ae80 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
1ae90 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
1aea0 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
1aeb0 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
1aec0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
1aed0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
1aee0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
1aef0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
1af00 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   an SQLITE_ERROR
1af10 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
1af20 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1af30 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  r is the number 
1af40 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
1af50 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
1af60 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
1af70 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69  te takes. If thi
1af80 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
1af90 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
1afa0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
1afb0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
1afc0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
1afd0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e  er of arguments.
1afe0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
1aff0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
1b000 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
1b010 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54   what .** [SQLIT
1b020 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
1b030 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
1b040 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
1b050 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
1b060 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
1b070 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
1b080 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
1b090 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
1b0a0 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
1b0b0 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
1b0c0 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
1b0d0 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
1b0e0 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
1b0f0 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
1b100 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
1b110 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
1b120 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  It is allowed to
1b130 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
1b140 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1b150 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
1b160 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
1b170 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
1b180 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
1b190 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
1b1a0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
1b1b0 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
1b1c0 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74  ep..** When mult
1b1d0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
1b1e0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
1b1f0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
1b200 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
1b210 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
1b220 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
1b230 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
1b240 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
1b250 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
1b260 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
1b270 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
1b280 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
1b290 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20  ot care what.** 
1b2a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
1b2b0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
1b2c0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
1b2d0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51  should be.** [SQ
1b2e0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
1b2f0 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   The fifth param
1b300 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
1b310 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
1b320 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1b330 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63  n.** of the func
1b340 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
1b350 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
1b360 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  nter using.** [s
1b370 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1b380 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
1b390 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
1b3a0 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
1b3b0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
1b3c0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
1b3d0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
1b3e0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
1b3f0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
1b400 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20  ment the SQL.** 
1b410 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
1b420 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
1b430 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
1b440 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
1b450 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ntation of.** th
1b460 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b  e xFunc callback
1b470 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
1b480 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
1b490 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
1b4a0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
1b4b0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
1b4c0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
1b4d0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
1b4e0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
1b4f0 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e  n.** of xStep an
1b500 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
1b510 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
1b520 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
1b530 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78   delete an.** ex
1b540 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
1b550 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
1b560 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
1b570 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
1b580 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a  on.** callback..
1b590 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d  **.** It is perm
1b5a0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
1b5b0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
1b5c0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
1b5d0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
1b5e0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
1b5f0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
1b600 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
1b610 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
1b620 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
1b630 65 72 69 6e 67 20 70 65 72 66 65 72 72 65 64 20  ering perferred 
1b640 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
1b650 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
1b660 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
1b670 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73  tation most clos
1b680 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
1b690 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
1b6a0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
1b6b0 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74   is used..*/.int
1b6c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1b6d0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
1b6e0 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  te3 *,.  const c
1b6f0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
1b700 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
1b710 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
1b720 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20    void*,.  void 
1b730 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
1b740 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
1b750 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
1b760 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
1b770 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1b780 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
1b790 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
1b7a0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
1b7b0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
1b7c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1b7d0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
1b7e0 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
1b7f0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
1b800 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
1b810 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
1b820 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
1b830 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
1b840 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
1b850 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
1b860 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
1b870 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b880 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
1b890 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
1b8a0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
1b8b0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
1b8c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b8d0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46  ext Encodings {F
1b8e0 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10267}.**.** The
1b8f0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
1b900 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
1b910 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
1b920 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
1b930 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
1b940 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
1b950 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1b960 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
1b970 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1b980 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
1b990 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
1b9a0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
1b9b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1b9c0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
1b9d0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
1b9e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1b9f0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1ba00 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
1ba10 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
1ba20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1ba30 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
1ba40 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
1ba50 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
1ba60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1ba70 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
1ba80 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1ba90 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63  F: Obsolete Func
1baa0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1bab0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
1bac0 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65  all now obsolete
1bad0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
1bae0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
1baf0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1bb00 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
1bb10 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20  de, we continue 
1bb20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68  to support.** th
1bb30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
1bb40 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76  However, new dev
1bb50 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74  elopment project
1bb60 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
1bb70 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
1bb80 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
1bb90 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
1bba0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
1bbb0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
1bbc0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
1bbd0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
1bbe0 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65  ell you want the
1bbf0 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  y do..*/.int sql
1bc00 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1bc10 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
1bc20 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  text*);.int sqli
1bc30 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
1bc40 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20  te3_stmt*);.int 
1bc50 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
1bc60 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
1bc70 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
1bc80 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
1bc90 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
1bca0 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20  ver(void);.void 
1bcb0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
1bcc0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e  leanup(void);.in
1bcd0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
1bce0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
1bcf0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
1bd00 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
1bd10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f  lite3_int64);../
1bd20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1bd30 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
1bd40 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
1bd50 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d 0a  Values {F15100}.
1bd60 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
1bd70 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
1bd80 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
1bd90 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
1bda0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
1bdb0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
1bdc0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
1bdd0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
1bde0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
1bdf0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
1be00 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
1be10 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
1be20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
1be30 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
1be40 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
1be50 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
1be60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1be70 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
1be80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1be90 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
1bea0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
1beb0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
1bec0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
1bed0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
1bee0 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
1bef0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
1bf00 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
1bf10 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1bf20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
1bf30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
1bf40 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
1bf50 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
1bf60 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
1bf70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1bf80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
1bf90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1bfa0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
1bfb0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
1bfc0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1bfd0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
1bfe0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1bff0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
1c000 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
1c010 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ding .** [sqlite
1c020 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20  3_column_blob | 
1c030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
1c040 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70   routines] excep
1c050 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65  t that .** these
1c060 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
1c070 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33   single [sqlite3
1c080 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72  _value*] pointer
1c090 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1c0a0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  n [sqlite3_stmt*
1c0b0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
1c0c0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
1c0d0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
1c0e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
1c0f0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
1c100 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
1c110 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
1c120 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1c130 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
1c140 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
1c150 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1c160 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
1c170 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1c180 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
1c190 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
1c1a0 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
1c1b0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
1c1c0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
1c1d0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
1c1e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
1c1f0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
1c200 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
1c210 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
1c220 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
1c230 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
1c240 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
1c250 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
1c260 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
1c270 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
1c280 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
1c290 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
1c2a0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
1c2b0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
1c2c0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
1c2d0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
1c2e0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
1c2f0 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
1c300 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
1c310 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
1c320 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
1c330 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 64   conversion is d
1c340 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20  one.  Otherwise 
1c350 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
1c360 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  curs.  The .** [
1c370 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
1c380 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
1c390 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
1c3a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
1c3b0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
1c3c0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
1c3d0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
1c3e0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
1c3f0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1c400 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
1c410 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
1c420 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
1c430 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
1c440 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
1c450 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
1c460 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
1c470 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
1c480 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
1c490 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
1c4a0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
1c4b0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
1c4c0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
1c4d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
1c4e0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a  ue_text16()].  .
1c4f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1c500 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
1c510 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
1c520 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
1c530 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1c540 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
1c550 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e sqlite3_value*
1c560 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20   parameters..** 
1c570 4f 72 2c 20 69 66 20 74 68 65 20 73 71 6c 69 74  Or, if the sqlit
1c580 65 33 5f 76 61 6c 75 65 2a 20 61 72 67 75 6d 65  e3_value* argume
1c590 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68  nt comes from th
1c5a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1c5b0 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e  n_value()].** in
1c5c0 74 65 72 66 61 63 65 2c 20 74 68 65 6e 20 74 68  terface, then th
1c5d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
1c5e0 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 66 72  uld be called fr
1c5f0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
1c600 61 64 0a 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b  ad.** that ran [
1c610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1c620 61 6c 75 65 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 63  alue()]..**.*/.c
1c630 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1c640 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
1c650 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1c660 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
1c670 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
1c680 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
1c690 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
1c6a0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
1c6b0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
1c6c0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
1c6d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
1c6e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
1c6f0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
1c700 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
1c710 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
1c720 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
1c730 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
1c740 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
1c750 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
1c760 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
1c770 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1c780 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
1c790 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
1c7a0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
1c7b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
1c7c0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
1c7d0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
1c7e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
1c7f0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
1c800 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1c810 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1c820 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
1c830 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1c840 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
1c850 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
1c860 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
1c870 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
1c880 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
1c890 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d  Context {F16210}
1c8a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
1c8b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
1c8c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
1c8d0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
1c8e0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
1c8f0 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
1c900 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
1c910 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 7b  ir state.  .** {
1c920 46 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73  F16211} The firs
1c930 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
1c940 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1c950 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69  text() routine i
1c960 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66  s.** is called f
1c970 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
1c980 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74  aggregate, SQLit
1c990 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74  e allocates nByt
1c9a0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  es of memory.** 
1c9b0 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f 72  zeros that memor
1c9c0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
1c9d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a   pointer to it..
1c9e0 2a 2a 20 7b 46 31 36 32 31 32 7d 20 4f 6e 20 73  ** {F16212} On s
1c9f0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
1ca00 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71  uent calls to sq
1ca10 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
1ca20 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72  context().** for
1ca30 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
1ca40 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
1ca50 65 78 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66  ex, the same buf
1ca60 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
1ca70 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 69 6d   {END}.** The im
1ca80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1ca90 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
1caa0 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65 74   can use the ret
1cab0 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
1cac0 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
1cad0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20  .**.** {F16213} 
1cae0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
1caf0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61  ally frees the a
1cb00 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20  llocated buffer 
1cb10 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
1cb20 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63  te.** query conc
1cb30 6c 75 64 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ludes. {END}.**.
1cb40 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1cb50 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
1cb60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a   a copy of the .
1cb70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1cb80 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
1cb90 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
1cba0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1cbb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1cbc0 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  e callback routi
1cbd0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
1cbe0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
1cbf0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
1cc00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1cc10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1cc20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
1cc30 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
1cc40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
1cc50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
1cc60 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
1cc70 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
1cc80 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
1cc90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
1cca0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
1ccb0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
1ccc0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
1ccd0 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a  ns {F16240}.**.*
1cce0 2a 20 7b 46 31 36 32 34 31 7d 20 54 68 65 20 73  * {F16241} The s
1ccf0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1cd00 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1cd10 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
1cd20 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
1cd30 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
1cd40 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
1cd50 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
1cd60 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65  r).** of the the
1cd70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1cd80 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
1cd90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
1cda0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
1cdb0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
1cdc0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
1cdd0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
1cde0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
1cdf0 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d   function. {END}
1ce00 0a 2a 2a 0a 2a 2a 20 7b 55 31 36 32 34 33 7d 20  .**.** {U16243} 
1ce10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
1ce20 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
1ce30 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
1ce40 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
1ce50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1ce60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
1ce70 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
1ce80 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
1ce90 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
1cea0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
1ceb0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
1cec0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
1ced0 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F16270}.**.** 
1cee0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
1cef0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
1cf00 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
1cf10 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
1cf20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
1cf30 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61  meta-data with a
1cf40 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
1cf50 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
1cf60 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
1cf70 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
1cf80 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
1cf90 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
1cfa0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
1cfb0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
1cfc0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
1cfd0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
1cfe0 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79  ed meta-data may
1cff0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
1d000 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
1d010 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
1d020 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
1d030 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
1d040 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
1d050 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
1d060 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
1d070 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
1d080 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
1d090 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61  ed as.** meta-da
1d0a0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
1d0b0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
1d0c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
1d0d0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
1d0e0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
1d0f0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
1d100 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
1d110 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
1d120 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
1d130 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
1d140 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
1d150 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
1d160 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
1d170 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
1d180 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
1d190 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
1d1a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ation..**.** {F1
1d1b0 36 32 37 31 7d 0a 2a 2a 20 54 68 65 20 73 71 6c  6271}.** The sql
1d1c0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1d1d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1d1e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d1f0 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  o the meta-data.
1d200 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
1d210 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1d220 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
1d230 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
1d240 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
1d250 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
1d260 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
1d270 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 32  nction..** {F162
1d280 37 32 7d 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64  72} If no meta-d
1d290 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
1d2a0 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  r been set for t
1d2b0 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65  he Nth.** argume
1d2c0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
1d2d0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
1d2e0 6f 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  oresponding func
1d2f0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a  tion parameter.*
1d300 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  * has changed si
1d310 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
1d320 61 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20  a was set, then 
1d330 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1d340 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ata().** returns
1d350 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1d360 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 35 7d 20  .**.** {F16275} 
1d370 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
1d380 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
1d390 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
1d3a0 74 61 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  ta-data.** point
1d3b0 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
1d3c0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
1d3d0 65 20 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20  e meta-data for 
1d3e0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
1d3f0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
1d400 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1d410 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  function. {END} 
1d420 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
1d430 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
1d440 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
1d450 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
1d460 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
1d470 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
1d480 6f 79 65 64 2e 20 0a 2a 2a 20 7b 46 31 36 32 37  oyed. .** {F1627
1d490 37 7d 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  7} If it is not 
1d4a0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
1d4b0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
1d4c0 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63  tructor .** func
1d4d0 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
1d4e0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
1d4f0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1d500 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
1d510 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65  he meta-data whe
1d520 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
1d530 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
1d540 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
1d550 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
1d560 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1d570 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
1d580 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b 45   comes first. {E
1d590 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ND}.**.** In pra
1d5a0 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
1d5b0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
1d5c0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
1d5d0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
1d5e0 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
1d5f0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
1d600 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
1d610 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
1d620 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
1d630 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
1d640 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d650 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
1d660 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
1d670 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
1d680 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
1d690 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
1d6a0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1d6b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
1d6c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
1d6d0 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
1d6e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1d6f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1d700 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
1d710 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
1d720 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1d730 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
1d740 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
1d750 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
1d760 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a  or {F10280}.**.*
1d770 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
1d780 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ial value for th
1d790 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
1d7a0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
1d7b0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
1d7c0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
1d7d0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
1d7e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
1d7f0 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
1d800 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
1d810 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
1d820 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
1d830 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
1d840 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
1d850 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
1d860 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
1d870 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1d880 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
1d890 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  he .** SQLITE_TR
1d8a0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
1d8b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
1d8c0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
1d8d0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
1d8e0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
1d8f0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
1d900 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
1d910 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
1d920 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
1d930 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
1d940 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
1d950 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
1d960 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
1d970 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
1d980 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
1d990 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
1d9a0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
1d9b0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
1d9c0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
1d9d0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
1d9e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
1d9f0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
1da00 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
1da10 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
1da20 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
1da30 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
1da40 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
1da50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1da60 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
1da70 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
1da80 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a  tion {F16400}.**
1da90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1daa0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
1dab0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
1dac0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
1dad0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
1dae0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
1daf0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
1db00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
1db10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
1db20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
1db30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
1db40 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
1db50 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1db60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
1db70 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
1db80 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
1db90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1dba0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
1dbb0 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20  _bind_*] family 
1dbc0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  of functions use
1dbd0 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c  d.** to bind val
1dbe0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
1dbf0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
1dc00 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
1dc10 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a  * Refer to the.*
1dc20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1dc30 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
1dc40 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74  ind_* documentat
1dc50 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69  ion] for.** addi
1dc60 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1dc70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30  on..**.** {F1640
1dc80 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  2} The sqlite3_r
1dc90 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
1dca0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
1dcb0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
1dcc0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
1dcd0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
1dce0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
1dcf0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
1dd00 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
1dd10 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1dd20 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
1dd30 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
1dd40 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1dd50 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1dd60 2e 20 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54  . .** {F16403} T
1dd70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
1dd80 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65  t_zeroblob() ine
1dd90 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
1dda0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
1ddb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
1ddc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
1ddd0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
1dde0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
1ddf0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
1de00 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
1de10 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
1de20 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
1de30 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
1de40 36 34 30 37 7d 20 54 68 65 20 73 71 6c 69 74 65  6407} The sqlite
1de50 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
1de60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
1de70 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1de80 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
1de90 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
1dea0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
1deb0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
1dec0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
1ded0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
1dee0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39  t..**.** {F16409
1def0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  } The sqlite3_re
1df00 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
1df10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1df20 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
1df30 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
1df40 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
1df50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
1df60 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
1df70 0a 2a 2a 20 7b 46 31 36 34 31 31 7d 20 53 51 4c  .** {F16411} SQL
1df80 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
1df90 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
1dfa0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
1dfb0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
1dfc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
1dfd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
1dfe0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
1dff0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
1e000 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1e010 20 7b 46 31 36 34 31 32 7d 20 53 51 4c 69 74 65   {F16412} SQLite
1e020 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
1e030 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
1e040 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
1e050 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
1e060 72 28 29 20 61 73 20 55 54 46 38 2e 20 20 7b 46  r() as UTF8.  {F
1e070 31 36 34 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a  16413} SQLite.**
1e080 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
1e090 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
1e0a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1e0b0 31 36 28 29 20 61 73 20 55 54 46 31 36 20 69 6e  16() as UTF16 in
1e0c0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
1e0d0 6f 72 64 65 72 2e 20 20 7b 46 31 36 34 31 34 7d  order.  {F16414}
1e0e0 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
1e0f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1e100 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1e110 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
1e120 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
1e130 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
1e140 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
1e150 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
1e160 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
1e170 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
1e180 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
1e190 74 65 72 2e 0a 2a 2a 20 7b 46 31 36 34 31 35 7d  ter..** {F16415}
1e1a0 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
1e1b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1e1c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
1e1d0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
1e1e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
1e1f0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1e200 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
1e210 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
1e220 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
1e230 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
1e240 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
1e250 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
1e260 67 65 2e 0a 2a 2a 20 7b 46 31 36 34 31 37 7d 20  ge..** {F16417} 
1e270 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
1e280 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
1e290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1e2a0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
1e2b0 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  nes make a copy 
1e2c0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1e2d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1e2e0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
1e2f0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 7b   they return.  {
1e300 45 4e 44 7d 20 48 65 6e 63 65 2c 20 74 68 65 20  END} Hence, the 
1e310 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
1e320 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
1e330 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
1e340 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
1e350 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
1e360 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  harm..**.** {F16
1e370 34 32 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  421} The sqlite3
1e380 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
1e390 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1e3a0 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74  s SQLite.** to t
1e3b0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e  hrow an error in
1e3c0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
1e3d0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
1e3e0 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20  s to long.** to 
1e3f0 72 65 70 72 65 73 65 6e 74 2e 20 20 7b 46 31 36  represent.  {F16
1e400 34 32 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33  422} The sqlite3
1e410 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
1e420 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75  interface.** cau
1e430 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
1e440 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
1e450 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
1e460 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   the a.** memory
1e470 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1e480 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33  ed..**.** {F1643
1e490 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  1} The sqlite3_r
1e4a0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
1e4b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
1e4c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
1e4d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
1e4e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
1e4f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
1e500 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1e510 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
1e520 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
1e530 75 6d 65 6e 74 2e 0a 2a 2a 20 7b 46 31 36 34 33  ument..** {F1643
1e540 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  2} The sqlite3_r
1e550 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
1e560 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
1e570 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
1e580 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
1e590 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
1e5a0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
1e5b0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
1e5c0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
1e5d0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
1e5e0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  rgument..**.** {
1e5f0 46 31 36 34 33 37 7d 20 54 68 65 20 73 71 6c 69  F16437} The sqli
1e600 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
1e610 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
1e620 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1e630 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
1e640 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1e650 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
1e660 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
1e670 34 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  41} The sqlite3_
1e680 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
1e690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
1e6a0 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69  xt16(), .** sqli
1e6b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1e6c0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
1e6d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
1e6e0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
1e6f0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
1e700 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
1e710 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1e720 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
1e730 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
1e740 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
1e750 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
1e760 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
1e770 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
1e780 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
1e790 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
1e7a0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
1e7b0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 7b 46 31 36  ctively..** {F16
1e7c0 34 34 32 7d 20 53 51 4c 69 74 65 20 74 61 6b 65  442} SQLite take
1e7d0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
1e7e0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
1e7f0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
1e800 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
1e810 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1e820 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
1e830 65 72 66 61 63 65 73 2e 0a 2a 2a 20 7b 46 31 36  erfaces..** {F16
1e840 34 34 34 7d 20 49 66 20 74 68 65 20 33 72 64 20  444} If the 3rd 
1e850 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1e860 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1e870 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
1e880 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
1e890 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
1e8a0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
1e8b0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
1e8c0 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67  meter .** throug
1e8d0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
1e8e0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 7b   character..** {
1e8f0 46 31 36 34 34 37 7d 20 49 66 20 74 68 65 20 33  F16447} If the 3
1e900 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1e910 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
1e920 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
1e930 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
1e940 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
1e950 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
1e960 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
1e970 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
1e980 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
1e990 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
1e9a0 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
1e9b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
1e9c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
1e9d0 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20  lt..** {F16451} 
1e9e0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
1e9f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1ea00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
1ea10 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
1ea20 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
1ea30 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
1ea40 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
1ea50 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
1ea60 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
1ea70 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
1ea80 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
1ea90 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65   blob result whe
1eaa0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
1eab0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
1eac0 72 65 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34  result..** {F164
1ead0 35 33 7d 20 49 66 20 74 68 65 20 34 74 68 20 70  53} If the 4th p
1eae0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1eaf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
1eb00 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
1eb10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
1eb20 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
1eb30 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
1eb40 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
1eb50 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1eb60 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
1eb70 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65   text or blob re
1eb80 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74  sult is constant
1eb90 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f   space and.** do
1eba0 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20  es not copy the 
1ebb0 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20  space or call a 
1ebc0 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20  destructor when 
1ebd0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
1ebe0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
1ebf0 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 34  sult..** {F16454
1ec00 7d 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  } If the 4th par
1ec10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1ec20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1ec30 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
1ec40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
1ec50 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
1ec60 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
1ec70 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1ec80 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
1ec90 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
1eca0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
1ecb0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
1ecc0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
1ecd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
1ece0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
1ecf0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 31 7d  ..**.** {F16461}
1ed00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
1ed10 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
1ed20 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
1ed30 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
1ed40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ed50 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
1ed60 62 65 20 61 20 63 6f 70 79 20 74 68 65 20 5b 73  be a copy the [s
1ed70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
1ed80 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
1ed90 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
1eda0 61 6d 65 74 65 72 2e 20 20 7b 46 31 36 34 36 33  ameter.  {F16463
1edb0 7d 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  } The.** sqlite3
1edc0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
1edd0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
1ede0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
1edf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
1ee00 20 73 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65   so that [sqlite
1ee10 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
1ee20 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
1ee30 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
1ee40 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
1ee50 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
1ee60 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
1ee70 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
1ee80 20 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31   harm..**.** {U1
1ee90 36 34 39 31 7d 20 54 68 65 73 65 20 72 6f 75 74  6491} These rout
1eea0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1eeb0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
1eec0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
1eed0 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e   .** than the on
1eee0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
1eef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1ef00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
1ef10 61 74 20 72 65 63 69 65 76 65 64 0a 2a 2a 20 74  at recieved.** t
1ef20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
1ef30 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
1ef40 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1ef50 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
1ef60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1ef70 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
1ef80 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1ef90 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1efa0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
1efb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
1efc0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
1efd0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
1efe0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1eff0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
1f000 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1f010 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
1f020 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1f030 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
1f040 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1f050 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
1f060 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1f070 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
1f080 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1f090 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
1f0a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
1f0b0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
1f0c0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
1f0d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
1f0e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1f0f0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1f100 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
1f110 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1f120 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
1f130 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1f140 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
1f150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
1f160 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1f170 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
1f180 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
1f190 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
1f1a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
1f1b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1f1c0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
1f1d0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
1f1e0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1f1f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
1f200 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1f210 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
1f220 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1f230 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
1f240 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
1f250 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1f260 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
1f270 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1f280 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
1f290 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1f2a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1f2b0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
1f2c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
1f2d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
1f2e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1f2f0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1f300 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
1f310 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f320 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
1f330 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
1f340 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a  es {F16600}.**.*
1f350 2a 20 7b 46 31 36 36 30 31 7d 0a 2a 2a 20 54 68  * {F16601}.** Th
1f360 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
1f370 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
1f380 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
1f390 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
1f3a0 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
1f3b0 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  e specified as t
1f3c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1f3d0 74 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  t. .**.** {F1660
1f3e0 32 7d 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  2}.** The name o
1f3f0 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74  f the new collat
1f400 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
1f410 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55  specified as a U
1f420 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
1f430 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
1f440 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
1f450 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
1f460 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
1f470 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
1f480 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74  string for sqlit
1f490 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1f4a0 69 6f 6e 31 36 28 29 2e 20 7b 46 31 36 36 30 33  ion16(). {F16603
1f4b0 7d 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a  } In all cases.*
1f4c0 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
1f4d0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
1f4e0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
1f4f0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ment..**.** {F16
1f500 36 30 34 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72  604}.** The thir
1f510 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  d argument may b
1f520 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
1f530 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55  stants [SQLITE_U
1f540 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TF8],.** [SQLITE
1f550 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51  _UTF16LE] or [SQ
1f560 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
1f570 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
1f580 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
1f590 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
1f5a0 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
1f5b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
1f5c0 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
1f5d0 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
1f5e0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
1f5f0 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  n or UTF-16 big-
1f600 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
1f610 65 6c 79 2e 20 7b 46 31 36 36 30 35 7d 20 54 68  ely. {F16605} Th
1f620 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
1f630 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
1f640 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
1f650 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
1f660 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
1f670 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
1f680 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
1f690 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
1f6a0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
1f6b0 54 46 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  TF16 in the nati
1f6c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66  ve byte order of
1f6d0 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
1f6e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  er..**.** {F1660
1f6f0 37 7d 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  7}.** A pointer 
1f700 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70  to the user supp
1f710 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73  lied routine mus
1f720 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
1f730 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75  he fifth.** argu
1f740 6d 65 6e 74 2e 20 7b 46 31 36 36 30 39 7d 20 49  ment. {F16609} I
1f750 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
1f760 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
1f770 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
1f780 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
1f790 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
1f7a0 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
1f7b0 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
1f7c0 20 7b 46 31 36 36 31 31 7d 20 45 61 63 68 20 74   {F16611} Each t
1f7d0 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
1f7e0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
1f7f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
1f800 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
1f810 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
1f820 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
1f830 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
1f840 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1f850 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1f860 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
1f870 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1f880 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
1f890 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
1f8a0 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 0a 2a  **.** {F16612}.*
1f8b0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1f8c0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
1f8d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
1f8e0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
1f8f0 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
1f900 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
1f910 65 64 20 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c  ed by a [length,
1f920 20 64 61 74 61 5d 20 70 61 69 72 20 61 6e 64 20   data] pair and 
1f930 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
1f940 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
1f950 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
1f960 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1f970 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
1f980 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
1f990 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
1f9a0 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63  {END} The applic
1f9b0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
1f9c0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
1f9d0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1f9e0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
1f9f0 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a  or positive if.*
1fa00 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  * the first stri
1fa10 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
1fa20 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
1fa30 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
1fa40 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e  econd.** string.
1fa50 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
1fa60 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
1fa70 20 7b 46 31 36 36 31 35 7d 0a 2a 2a 20 54 68 65   {F16615}.** The
1fa80 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1fa90 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
1faa0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
1fab0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1fac0 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74  on().** excapt t
1fad0 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
1fae0 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
1faf0 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
1fb00 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
1fb10 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 7b 46 31 36  collation.  {F16
1fb20 36 31 37 7d 20 54 68 65 20 64 65 73 74 72 75 63  617} The destruc
1fb30 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
1fb40 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
1fb50 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
1fb60 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
1fb70 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
1fb80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
1fb90 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
1fba0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
1fbb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1fbc0 32 28 29 2e 0a 2a 2a 20 7b 46 31 36 36 31 38 7d  2()..** {F16618}
1fbd0 20 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65    Collations are
1fbe0 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a   destroyed when.
1fbf0 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  ** they are over
1fc00 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20  ridden by later 
1fc10 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
1fc20 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
1fc30 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20  functions.** or 
1fc40 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  when the [sqlite
1fc50 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
1fc60 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73  dle is closed us
1fc70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
1fc80 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  se()]..*/.int sq
1fc90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1fca0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
1fcb0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
1fcc0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
1fcd0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
1fce0 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
1fcf0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
1fd00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
1fd10 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1fd20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
1fd30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1fd40 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
1fd50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1fd60 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
1fd70 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
1fd80 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
1fd90 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1fda0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1fdb0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
1fdc0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
1fdd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1fde0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
1fdf0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
1fe00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
1fe10 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
1fe20 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
1fe30 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
1fe40 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1fe50 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
1fe60 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
1fe70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
1fe80 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
1fe90 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a  lbacks {F16700}.
1fea0 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 31 7d 0a 2a  **.** {F16701}.*
1feb0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
1fec0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
1fed0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
1fee0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
1fef0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
1ff00 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
1ff10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ff20 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
1ff30 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
1ff40 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
1ff50 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
1ff60 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
1ff70 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
1ff80 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71  quence is.** req
1ff90 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  uired..**.** {F1
1ffa0 36 37 30 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20  6702}.** If the 
1ffb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
1ffc0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
1ffd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
1ffe0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
1fff0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
20000 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
20010 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
20020 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
20030 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
20040 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
20050 20 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {F16703} If sql
20060 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
20070 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
20080 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20  d, the names.** 
20090 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
200a0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
200b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
200c0 72 2e 20 7b 46 31 36 37 30 34 7d 20 41 20 63 61  r. {F16704} A ca
200d0 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ll to either.** 
200e0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
200f0 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
20100 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
20110 46 31 36 37 30 35 7d 20 57 68 65 6e 20 74 68 65  F16705} When the
20120 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20130 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
20140 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
20150 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
20160 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
20170 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
20180 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
20190 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
201a0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
201b0 31 36 28 29 2e 20 7b 46 31 36 37 30 36 7d 20 54  16(). {F16706} T
201c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
201d0 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
201e0 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 7b  se.** handle.  {
201f0 46 31 36 37 30 37 7d 20 54 68 65 20 74 68 69 72  F16707} The thir
20200 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
20210 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
20220 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
20230 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
20240 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
20250 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
20260 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66  t.** desirable f
20270 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
20280 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75  tion sequence fu
20290 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
202a0 0a 2a 2a 20 7b 46 31 36 37 30 38 7d 20 54 68 65  .** {F16708} The
202b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
202c0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
202d0 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
202e0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
202f0 6e 63 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  nce. {END}.**.**
20300 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
20310 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
20320 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
20330 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
20340 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
20350 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
20360 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
20370 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
20380 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
20390 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
203a0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
203b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
203c0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
203d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
203e0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
203f0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
20400 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
20410 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
20420 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
20430 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
20440 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
20450 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
20460 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
20470 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
20480 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
20490 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
204a0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
204b0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
204c0 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
204d0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
204e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
204f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
20500 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
20510 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
20520 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
20530 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
20540 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
20550 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
20560 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
20570 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
20580 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
20590 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
205a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
205b0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
205c0 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
205d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
205e0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
205f0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
20600 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
20610 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
20620 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
20630 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
20640 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
20650 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
20660 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
20670 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
20680 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
20690 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
206a0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
206b0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
206c0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
206d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
206e0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
206f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20710 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
20720 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
20730 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
20740 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
20750 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
20760 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
20770 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78  REF:  Suspend Ex
20780 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
20790 6f 72 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30  ort Time {F10530
207a0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 31 7d  }.**.** {F10531}
207b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
207c0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ep() function.**
207d0 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
207e0 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
207f0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
20800 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
20810 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
20820 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
20830 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
20840 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35  ter..**.** {F105
20850 33 32 7d 20 49 66 20 74 68 65 20 6f 70 65 72 61  32} If the opera
20860 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
20870 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
20880 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
20890 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64   .** millisecond
208a0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
208b0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
208c0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
208d0 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65  up to .** the ne
208e0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 7b 46  arest second. {F
208f0 31 30 35 33 33 7d 20 54 68 65 20 6e 75 6d 62 65  10533} The numbe
20900 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
20910 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
20920 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65  lly .** requeste
20930 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
20940 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
20950 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
20960 46 31 30 35 33 34 7d 20 53 51 4c 69 74 65 20 69  F10534} SQLite i
20970 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
20980 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
20990 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
209a0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
209b0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
209c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
209d0 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  {END}.*/.int sql
209e0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
209f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20a00 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  :  Name Of The F
20a10 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
20a20 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46  mporary Files {F
20a30 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20  10310}.**.** If 
20a40 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
20a50 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
20a60 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
20a70 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
20a80 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
20a90 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
20aa0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
20ab0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
20ac0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
20ad0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
20ae0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
20af0 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
20b00 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
20b10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
20b20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
20b30 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
20b40 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
20b50 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
20b60 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
20b70 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f  s not safe to mo
20b80 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
20b90 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61  le once a databa
20ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
20bb0 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64   has been opened
20bc0 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  .  It is intende
20bd0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
20be0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
20bf0 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
20c00 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
20c10 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
20c20 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
20c30 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
20c40 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
20c50 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68   and remain unch
20c60 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72  anged thereafter
20c70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
20c80 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
20c90 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
20ca0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20cb0 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  :  Test To See I
20cc0 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49  f The Database I
20cd0 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
20ce0 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a   Mode {F12930}.*
20cf0 2a 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54 68  *.** {F12931} Th
20d00 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
20d10 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
20d20 66 61 63 65 73 20 72 65 74 75 72 6e 73 20 6e 6f  faces returns no
20d30 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
20d40 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
20d50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20d60 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
20d70 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
20d80 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
20d90 65 6c 79 2e 20 7b 46 31 32 39 33 32 7d 20 20 41  ely. {F12932}  A
20da0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
20db0 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75  s on.** by defau
20dc0 6c 74 2e 20 20 7b 46 31 32 39 33 33 7d 20 41 75  lt.  {F12933} Au
20dd0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
20de0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42   disabled by a B
20df0 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 2e 0a  EGIN statement..
20e00 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74 6f  ** {F12934} Auto
20e10 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
20e20 65 65 6e 61 62 6c 65 64 20 62 79 20 61 20 43 4f  eenabled by a CO
20e30 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b  MMIT or ROLLBACK
20e40 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66  . {END}.**.** If
20e50 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
20e60 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
20e70 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
20e80 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
20e90 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
20ea0 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69  ctions (errors i
20eb0 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
20ec0 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
20ed0 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  IOERR], .** [SQL
20ee0 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
20ef0 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
20f00 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
20f10 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
20f20 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
20f30 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
20f40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
20f50 7b 46 31 32 39 33 35 7d 20 54 68 65 20 6f 6e 6c  {F12935} The onl
20f60 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
20f70 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65 20 61   out if SQLite a
20f80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
20f90 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
20fa0 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
20fb0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
20fc0 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
20fd0 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  on. {END}.**.** 
20fe0 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74  {U12936} If anot
20ff0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
21000 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
21010 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
21020 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
21030 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
21040 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
21050 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
21060 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
21070 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 7b 45 4e  s undefined. {EN
21080 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D}.*/.int sqlite
21090 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
210a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
210b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46 69  ** CAPI3REF:  Fi
210c0 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
210d0 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
210e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b  ared Statement {
210f0 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F13120}.**.** {F
21100 31 33 31 32 31 7d 20 54 68 65 20 73 71 6c 69 74  13121} The sqlit
21110 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
21120 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
21130 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  s the [sqlite3*]
21140 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
21150 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b   to which a.** [
21160 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
21170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21180 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 7b  t] belongs..** {
21190 46 31 33 31 32 32 7d 20 74 68 65 20 64 61 74 61  F13122} the data
211a0 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75  base handle retu
211b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
211c0 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  db_handle.** is 
211d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
211e0 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
211f0 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61  s.** the first a
21200 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
21210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21220 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
21230 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61  iants.** that wa
21240 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
21250 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
21260 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
21270 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
21280 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
21290 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
212a0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
212b0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
212c0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
212d0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
212e0 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12950}.**.** {F1
212f0 32 39 35 31 7d 20 54 68 65 20 73 71 6c 69 74 65  2951} The sqlite
21300 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
21310 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
21320 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
21330 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
21340 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
21350 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
21360 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a  is committed..**
21370 20 7b 46 31 32 39 35 32 7d 20 41 6e 79 20 63 61   {F12952} Any ca
21380 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
21390 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
213a0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
213b0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
213c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
213d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
213e0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 7b 46 31  erridden..** {F1
213f0 32 39 35 33 7d 20 54 68 65 20 73 71 6c 69 74 65  2953} The sqlite
21400 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
21410 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
21420 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
21430 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
21440 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
21450 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
21460 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
21470 2a 2a 20 7b 46 31 32 39 35 34 7d 20 41 6e 79 20  ** {F12954} Any 
21480 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
21490 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
214a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
214b0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
214c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
214d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
214e0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 7b  overridden..** {
214f0 46 31 32 39 35 36 7d 20 54 68 65 20 70 41 72 67  F12956} The pArg
21500 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
21510 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74  sed through.** t
21520 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  o the callback. 
21530 20 7b 46 31 32 39 35 37 7d 20 49 66 20 74 68 65   {F12957} If the
21540 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
21550 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
21560 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20  ion .** returns 
21570 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
21580 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
21590 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
215a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  llback..**.** {F
215b0 31 32 39 35 38 7d 20 49 66 20 61 6e 6f 74 68 65  12958} If anothe
215c0 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
215d0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
215e0 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72  ered, its.** pAr
215f0 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
21600 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
21610 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
21620 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 39 7d  ..**.** {F12959}
21630 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
21640 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
21650 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
21660 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36  ck..**.** {F1296
21670 31 7d 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  1} For the purpo
21680 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
21690 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
216a0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
216b0 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  een .** rolled b
216c0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
216d0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
216e0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
216f0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
21700 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
21710 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
21720 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
21730 20 6f 63 63 75 72 2e 0a 2a 2a 20 7b 46 31 32 39   occur..** {F129
21740 36 32 7d 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  62} The rollback
21750 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
21760 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
21770 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
21780 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
21790 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
217a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
217b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
217c0 73 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 36 34 7d  sed..** {F12964}
217d0 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
217e0 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
217f0 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
21800 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c  action is.** rol
21810 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
21820 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61   a commit callba
21830 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d  ck returned non-
21840 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20  zero..** <todo> 
21850 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f  Check on this </
21860 74 6f 64 6f 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  todo> {END}.**.*
21870 2a 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65  * These are expe
21880 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
21890 63 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a  ces and are subj
218a0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a  ect to change..*
218b0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
218c0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
218d0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
218e0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
218f0 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
21900 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
21910 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
21920 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
21930 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
21940 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
21950 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
21960 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12970}.**.** {
21970 46 31 32 39 37 31 7d 20 54 68 65 20 73 71 6c 69  F12971} The sqli
21980 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
21990 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
219a0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
219b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ack function wit
219c0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
219d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69  onnection identi
219e0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
219f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
21a00 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
21a10 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
21a20 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
21a30 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
21a40 7b 46 31 32 39 37 32 7d 20 41 6e 79 20 63 61 6c  {F12972} Any cal
21a50 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
21a60 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
21a70 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f  this function fo
21a80 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64  r the same .** d
21a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21aa0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
21ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 34 7d  ..**.** {F12974}
21ac0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
21ad0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
21ae0 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
21af0 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
21b00 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70   a .** row is up
21b10 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
21b20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20  or deleted. .** 
21b30 7b 46 31 32 39 37 36 7d 20 54 68 65 20 66 69 72  {F12976} The fir
21b40 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
21b50 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a  he callback is.*
21b60 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  * a copy of the 
21b70 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
21b80 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
21b90 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 7b 46 31 32  _hook()..** {F12
21ba0 39 37 37 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  977} The second 
21bb0 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67  callback .** arg
21bc0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
21bd0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
21be0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
21bf0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
21c00 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  TE],.** dependin
21c10 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
21c20 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
21c30 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
21c40 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 7b 46  e invoked..** {F
21c50 31 32 39 37 38 7d 20 54 68 65 20 74 68 69 72 64  12978} The third
21c60 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20   and .** fourth 
21c70 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
21c80 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
21c90 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
21ca0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a  e database and .
21cb0 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  ** table name co
21cc0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
21cd0 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 7b 46  ected row..** {F
21ce0 31 32 39 37 39 7d 20 54 68 65 20 66 69 6e 61 6c  12979} The final
21cf0 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
21d00 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72  ter is .** the r
21d10 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e  owid of the row.
21d20 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 49 6e 20  .** {F12981} In 
21d30 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
21d40 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
21d50 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a  he rowid after .
21d60 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61  ** the update ta
21d70 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
21d80 20 7b 46 31 32 39 38 33 7d 20 54 68 65 20 75 70   {F12983} The up
21d90 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
21da0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
21db0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
21dc0 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
21dd0 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
21de0 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
21df0 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a  ite_sequence)..*
21e00 2a 0a 2a 2a 20 7b 46 31 32 39 38 34 7d 20 49 66  *.** {F12984} If
21e10 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
21e20 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
21e30 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
21e40 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69   pArg value.** i
21e50 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46 31  s returned.  {F1
21e60 32 39 38 35 7d 20 4f 74 68 65 72 77 69 73 65 20  2985} Otherwise 
21e70 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
21e80 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
21e90 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
21ea0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
21eb0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
21ec0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
21ed0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
21ee0 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
21ef0 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
21f00 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65  API3REF:  Enable
21f10 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
21f20 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b  ed Pager Cache {
21f30 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F10330}.**.** {F
21f40 31 30 33 33 31 7d 0a 2a 2a 20 54 68 69 73 20 72  10331}.** This r
21f50 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
21f60 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
21f70 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
21f80 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
21f90 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
21fa0 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
21fb0 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74  en connections t
21fc0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
21fd0 61 73 65 2e 0a 2a 2a 20 7b 46 31 30 33 33 32 7d  ase..** {F10332}
21fe0 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65  .** Sharing is e
21ff0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
22000 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61  gument is true a
22010 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
22020 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  he argument.** i
22030 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  s false..**.** {
22040 46 31 30 33 33 33 7d 20 43 61 63 68 65 20 73 68  F10333} Cache sh
22050 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
22060 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a   and disabled.**
22070 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
22080 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54 68  rocess. {END} Th
22090 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
220a0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
220b0 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e  ion 3.5.0..** In
220c0 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20   prior versions 
220d0 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72 69  of SQLite, shari
220e0 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65  ng was.** enable
220f0 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
22100 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65  r each thread se
22110 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
22120 7b 46 31 30 33 33 34 7d 0a 2a 2a 20 54 68 65 20  {F10334}.** The 
22130 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
22140 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
22150 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
22160 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
22170 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
22180 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
22190 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
221a0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
221b0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 7b 46  open16()]..** {F
221c0 31 30 33 33 35 7d 20 45 78 69 73 74 69 6e 67 20  10335} Existing 
221d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
221e0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
221f0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
22200 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
22210 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
22220 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
22230 70 65 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  pened. {END}.**.
22240 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
22250 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
22260 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
22270 61 63 68 65 2e 20 20 7b 46 31 30 33 33 36 7d 20  ache.  {F10336} 
22280 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63  When shared.** c
22290 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
222a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
222b0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41  eate_module()] A
222c0 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  PI used to regis
222d0 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  ter.** virtual t
222e0 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79  ables will alway
222f0 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
22300 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  r. {END}.**.** {
22310 46 31 30 33 33 37 7d 20 54 68 69 73 20 72 6f 75  F10337} This rou
22320 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
22330 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
22340 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20  ed cache was.** 
22350 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
22360 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  led successfully
22370 2e 20 20 7b 46 31 30 33 33 38 7d 20 41 6e 20 5b  .  {F10338} An [
22380 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
22390 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73  rror code].** is
223a0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
223b0 69 73 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ise. {END}.**.**
223c0 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65 64   {F10339} Shared
223d0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
223e0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b  ed by default. {
223f0 45 4e 44 7d 20 42 75 74 20 74 68 69 73 20 6d 69  END} But this mi
22400 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
22410 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
22420 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
22430 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
22440 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
22450 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
22460 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
22470 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2f 0a 69  explicitly..*/.i
22480 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
22490 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
224a0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
224b0 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54  3REF:  Attempt T
224c0 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
224d0 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a  ry {F17340}.**.*
224e0 2a 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20 73  * {F17341} The s
224f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
22500 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
22510 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a  e attempts to.**
22520 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
22530 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
22540 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
22550 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
22560 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  y.** allocations
22570 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
22580 61 62 61 73 65 20 6c 61 62 72 61 72 79 2e 20 7b  abase labrary. {
22590 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65  END}  Memory use
225a0 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61  d.** to cache da
225b0 74 61 62 61 73 65 20 70 61 67 65 73 20 74 6f 20  tabase pages to 
225c0 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
225d0 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
225e0 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65  e of.** non-esse
225f0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 7b  ntial memory.  {
22600 46 31 36 33 34 32 7d 20 73 71 6c 69 74 65 33 5f  F16342} sqlite3_
22610 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
22620 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
22630 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
22640 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20  actually freed, 
22650 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
22660 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74  ore or less.** t
22670 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
22680 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74  equested..*/.int
22690 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
226a0 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
226b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
226c0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
226d0 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31 37  n Heap Size {F17
226e0 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  350}.**.** {F163
226f0 35 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  51} The sqlite3_
22700 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
22710 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70  ) interface.** p
22720 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
22730 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
22740 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
22750 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
22760 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51  located.** by SQ
22770 4c 69 74 65 2e 20 7b 46 31 36 33 35 32 7d 20 49  Lite. {F16352} I
22780 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c  f an internal al
22790 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75  location is requ
227a0 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77  ested .** that w
227b0 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 20  ould exceed the 
227c0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
227d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
227e0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a  e_memory()] is.*
227f0 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72  * invoked one or
22800 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
22810 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
22820 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
22830 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61  ocation.** is ma
22840 64 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  de. {END}.**.** 
22850 7b 46 31 36 33 35 33 7d 20 54 68 65 20 6c 69 6d  {F16353} The lim
22860 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
22870 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 0a  ft", because if.
22880 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
22890 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61  ase_memory()] ca
228a0 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66  nnot.** free suf
228b0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
228c0 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
228d0 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
228e0 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
228f0 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
22900 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
22910 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
22920 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
22930 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 0a 2a 2a  *.** {F16354}.**
22940 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a   A negative or z
22950 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
22960 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
22970 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
22980 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
22990 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
229a0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
229b0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
229c0 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
229d0 75 73 74 65 64 2e 0a 2a 2a 20 7b 46 31 36 33 35  usted..** {F1635
229e0 35 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  5} The default v
229f0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
22a00 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
22a10 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  zero..**.** SQLi
22a20 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20  te makes a best 
22a30 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20  effort to honor 
22a40 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
22a50 6d 69 74 2e 20 20 0a 2a 2a 20 7b 46 31 36 33 35  mit.  .** {F1635
22a60 36 7d 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  6} But if the so
22a70 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
22a80 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 2c 20 65 78  nnot honored, ex
22a90 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
22aa0 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
22ab0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
22ac0 63 61 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20 54  cation. {END}  T
22ad0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
22ae0 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c  imit is .** call
22af0 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
22b00 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
22b10 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
22b20 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
22b30 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
22b40 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
22b50 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
22b60 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
22b70 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
22b80 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
22b90 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
22ba0 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
22bb0 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
22bc0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
22bd0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
22be0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
22bf0 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
22c00 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
22c10 7b 46 31 36 33 35 37 7d 20 54 68 65 20 76 61 6c  {F16357} The val
22c20 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
22c30 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
22c40 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
22c50 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
22c60 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
22c70 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
22c80 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d 20   threads. {END} 
22c90 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
22ca0 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
22cb0 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
22cc0 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
22cd0 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
22ce0 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
22cf0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
22d00 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
22d10 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
22d20 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61 63  API3REF:  Extrac
22d30 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74  t Metadata About
22d40 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54   A Column Of A T
22d50 61 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a  able {F12850}.**
22d60 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
22d70 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61  .** returns meta
22d80 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  -data about a sp
22d90 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
22da0 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
22db0 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63  base.** table ac
22dc0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
22dd0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  he connection ha
22de0 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74  ndle passed as t
22df0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
22e00 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a  n .** argument..
22e10 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e  **.** The column
22e20 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
22e30 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
22e40 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
22e50 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a  arameters to .**
22e60 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
22e70 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
22e80 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
22e90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
22ea0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
22eb0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20   "main", "temp" 
22ec0 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
22ed0 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
22ee0 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
22ef0 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
22f00 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c  LL. If it is NUL
22f10 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
22f20 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
22f30 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
22f40 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
22f50 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
22f60 72 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74  rithm as the dat
22f70 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65  abase engine use
22f80 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65  s to .** resolve
22f90 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
22fa0 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
22fb0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
22fc0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
22fd0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
22fe0 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
22ff0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a  ble and column .
23000 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
23010 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
23020 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
23030 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
23040 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79  rameters .** may
23050 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
23060 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  Meta information
23070 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
23080 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
23090 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
230a0 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
230b0 20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75   5th and subsequ
230c0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
230d0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
230e0 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a   Any of these .*
230f0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  * arguments may 
23100 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  be NULL, in whic
23110 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
23120 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
23130 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66   of meta .** inf
23140 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69  ormation is ommi
23150 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  tted..**.** <pre
23160 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20  >.** Parameter  
23170 20 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20     Output Type  
23180 20 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a      Description.
23190 2a 2a 20 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 2d 2d 2d 2d  ----------------
231b0 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35  ------.**.**   5
231c0 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
231d0 20 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61   char*      Data
231e0 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20   type.**   6th  
231f0 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
23200 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20  r*      Name of 
23210 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c  the default coll
23220 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a  ation sequence .
23230 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20  **   7th        
23240 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
23250 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
23260 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
23270 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
23280 2a 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20  *   8th         
23290 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
232a0 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
232b0 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
232c0 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
232d0 2a 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20  *   9th         
232e0 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
232f0 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
23300 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45  umn is AUTOINCRE
23310 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  MENT.** </pre>.*
23320 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f  *.**.** The memo
23330 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ry pointed to by
23340 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70   the character p
23350 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
23360 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63   for the .** dec
23370 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
23380 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
23390 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
233a0 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
233b0 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  t .** call to an
233c0 79 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e  y sqlite API fun
233d0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
233e0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
233f0 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
23400 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20  a view, then an 
23410 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
23420 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
23430 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
23440 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
23450 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
23460 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47  and an .** INTEG
23470 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63  ER PRIMARY KEY c
23480 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
23490 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
234a0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
234b0 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  put .** paramete
234c0 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
234d0 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
234e0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49  clared column. I
234f0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
23500 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
23510 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c  ared IPK column,
23520 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
23530 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
23540 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f  set as .** follo
23550 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
23560 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
23570 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
23580 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
23590 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
235a0 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
235b0 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
235c0 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
235d0 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
235e0 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  0.** </pre>.**.*
235f0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
23600 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
23610 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
23620 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
23630 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
23640 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
23650 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
23660 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
23670 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
23680 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
23690 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65  und, an SQLITE e
236a0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
236b0 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72  urned and an err
236c0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65  or message.** le
236d0 66 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  ft in the databa
236e0 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65  se handle (to be
236f0 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
23700 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
23710 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ))..**.** This A
23720 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
23730 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
23740 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
23750 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
23760 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
23770 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72  N_METADATA prepr
23780 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
23790 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
237a0 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
237b0 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
237c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
237d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
237e0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
237f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23800 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
23810 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
23820 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
23830 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
23840 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
23850 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
23860 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
23870 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
23880 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
23890 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
238a0 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
238b0 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
238c0 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
238d0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
238e0 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
238f0 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
23900 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
23910 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
23920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23930 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
23940 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
23950 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
23960 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
23970 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
23980 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
23990 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
239a0 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
239b0 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
239c0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
239d0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
239e0 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
239f0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
23a00 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
23a10 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d  tension {F12600}
23a20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20  .**.** {F12601} 
23a30 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
23a40 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
23a50 65 72 66 61 63 65 0a 2a 2a 20 61 74 74 65 6d 70  erface.** attemp
23a60 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51  ts to load an SQ
23a70 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
23a80 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
23a90 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   in the file.** 
23aa0 7a 46 69 6c 65 2e 20 7b 46 31 32 36 30 32 7d 20  zFile. {F12602} 
23ab0 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  The entry point 
23ac0 69 73 20 7a 50 72 6f 63 2e 20 7b 46 31 32 36 30  is zProc. {F1260
23ad0 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  3} zProc may be 
23ae0 30 0a 2a 2a 20 69 6e 20 77 68 69 63 68 20 63 61  0.** in which ca
23af0 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  se the name of t
23b00 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64  he entry point d
23b10 65 66 61 75 6c 74 73 0a 2a 2a 20 74 6f 20 22 73  efaults.** to "s
23b20 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e  qlite3_extension
23b30 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _init"..**.** {F
23b40 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74  12604} The sqlit
23b50 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
23b60 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68  n() interface sh
23b70 61 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  all.** return [S
23b80 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
23b90 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45  cess and [SQLITE
23ba0 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74  _ERROR] if somet
23bb0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
23bc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 35 7d 0a  .**.** {F12605}.
23bd0 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  ** If an error o
23be0 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
23bf0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
23c00 6e 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  n the.** sqlite3
23c10 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
23c20 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ) interface shal
23c30 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 66 69 6c  l attempt to fil
23c40 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
23c50 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61   .** error messa
23c60 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69  ge text stored i
23c70 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
23c80 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
23c90 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45  malloc()]..** {E
23ca0 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67  ND}  The calling
23cb0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
23cc0 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72   free this memor
23cd0 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20  y.** by calling 
23ce0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
23cf0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 36 7d  ..**.** {F12606}
23d00 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** Extension lo
23d10 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e  ading must be en
23d20 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
23d30 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
23d40 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
23d50 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
23d60 67 20 74 68 69 73 20 41 50 49 20 6f 72 20 61 6e  g this API or an
23d70 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
23d80 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
23d90 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
23da0 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  ension(.  sqlite
23db0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
23dc0 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65  /* Load the exte
23dd0 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20  nsion into this 
23de0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23df0 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
23e00 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f  har *zFile,    /
23e10 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68  * Name of the sh
23e20 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e  ared library con
23e30 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f  taining extensio
23e40 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
23e50 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20  r *zProc,    /* 
23e60 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65  Entry point.  De
23e70 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65  rived from zFile
23e80 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20   if 0 */.  char 
23e90 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20  **pzErrMsg      
23ea0 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65   /* Put error me
23eb0 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f  ssage here if no
23ec0 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  t 0 */.);../*.**
23ed0 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62   CAPI3REF:  Enab
23ee0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
23ef0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
23f00 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53  {F12620}.**.** S
23f10 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
23f20 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
23f30 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
23f40 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
23f50 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
23f60 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
23f70 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
23f80 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
23f90 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
23fa0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
23fb0 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
23fc0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
23fd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   the following.*
23fe0 2a 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65  * API is provide
23ff0 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
24000 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
24010 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
24020 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66  sm on and.** off
24030 2e 20 20 7b 46 31 32 36 32 32 7d 20 49 74 20 69  .  {F12622} It i
24040 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
24050 2e 20 7b 45 4e 44 7d 20 53 65 65 20 74 69 63 6b  . {END} See tick
24060 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20  et #1863..**.** 
24070 7b 46 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68  {F12621} Call th
24080 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  e sqlite3_enable
24090 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
240a0 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 74  ) routine.** wit
240b0 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75  h onoff==1 to tu
240c0 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  rn extension loa
240d0 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63  ding on.** and c
240e0 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
240f0 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20  f==0 to turn it 
24100 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 20  back off again. 
24110 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  {END}.*/.int sql
24120 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
24130 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
24140 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
24150 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
24160 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67  REF: Make Arrang
24170 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61  ements To Automa
24180 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20  tically Load An 
24190 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 34  Extension {F1264
241a0 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 31  0}.**.** {F12641
241b0 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  } This function.
241c0 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ** registers an 
241d0 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20  extension entry 
241e0 70 6f 69 6e 74 20 74 68 61 74 20 69 73 20 61 75  point that is au
241f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f  tomatically invo
24200 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20  ked.** whenever 
24210 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
24220 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
24230 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
24240 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
24250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
24260 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ], or [sqlite3_o
24270 70 65 6e 5f 76 32 28 29 5d 2e 20 7b 45 4e 44 7d  pen_v2()]. {END}
24280 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
24290 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
242a0 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
242b0 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
242c0 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
242d0 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
242e0 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
242f0 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
24300 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
24310 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65  all new database
24320 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a   connections..**
24330 0a 2a 2a 20 7b 46 31 32 36 34 32 7d 20 44 75 70  .** {F12642} Dup
24340 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
24350 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
24360 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
24370 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a  outine multiple.
24380 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
24390 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
243a0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
243b0 0a 2a 2a 20 7b 46 31 32 36 34 33 7d 20 54 68 69  .** {F12643} Thi
243c0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
243d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
243e0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61  e extension in a
243f0 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20  n array.** that 
24400 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
24410 20 73 71 6c 69 74 65 5f 6d 61 6c 6c 6f 63 28 29   sqlite_malloc()
24420 2e 20 7b 45 4e 44 7d 20 49 66 20 79 6f 75 20 72  . {END} If you r
24430 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  un a memory leak
24440 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79  .** checker on y
24450 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20  our program and 
24460 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61  it reports a lea
24470 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69  k because of thi
24480 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e  s.** array, then
24490 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
244a0 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
244b0 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 0a 2a  nsion()] prior.*
244c0 2a 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f  * to shutdown to
244d0 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79   free the memory
244e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 34 7d  ..**.** {F12644}
244f0 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   Automatic exten
24500 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f  sions apply acro
24510 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  ss all threads. 
24520 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
24530 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78   interface is ex
24540 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
24550 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
24560 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61  nge or.** remova
24570 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  l in future rele
24580 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
24590 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
245a0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
245b0 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  id *xEntryPoint)
245c0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
245d0 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
245e0 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
245f0 61 64 69 6e 67 20 7b 46 31 32 36 36 30 7d 0a 2a  ading {F12660}.*
24600 2a 0a 2a 2a 20 7b 46 31 32 36 36 31 7d 20 54 68  *.** {F12661} Th
24610 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
24620 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75  bles all previou
24630 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a  sly registered.*
24640 2a 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65  * automatic exte
24650 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 54  nsions. {END}  T
24660 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  his.** routine u
24670 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
24680 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73   of all prior [s
24690 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63  qlite3_automatic
246a0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
246b0 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   calls..**.** {F
246c0 31 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c  12662} This call
246d0 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61   disabled automa
246e0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
246f0 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b  n all threads. {
24700 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
24710 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
24720 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
24730 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
24740 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c  ge or.** removal
24750 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
24760 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
24770 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
24780 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
24790 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a  ion(void);.../*.
247a0 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
247b0 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
247c0 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
247d0 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
247e0 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  *****.**.** The 
247f0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
24800 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
24810 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
24820 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
24830 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
24840 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
24850 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
24860 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
24870 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
24880 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
24890 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
248a0 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
248b0 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
248c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
248d0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
248e0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a  echanism stabliz
248f0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
24900 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
24910 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
24920 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
24930 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
24940 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
24950 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
24960 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
24970 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
24980 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
24990 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
249a0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
249b0 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
249c0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
249d0 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
249e0 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
249f0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
24a00 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
24a10 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
24a20 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
24a30 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
24a40 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
24a50 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20  ./*.** A module 
24a60 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69  is a class of vi
24a70 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45  rtual tables.  E
24a80 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65  ach module is de
24a90 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69  fined.** by an i
24aa0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66  nstance of the f
24ab0 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
24ac0 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74  re.  This struct
24ad0 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20  ure consists.** 
24ae0 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64  mostly of method
24af0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
24b00 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
24b10 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69  te3_module {.  i
24b20 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
24b30 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71  nt (*xCreate)(sq
24b40 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
24b50 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
24b60 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
24b70 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
24b80 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
24b90 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
24ba0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
24bb0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e  *);.  int (*xCon
24bc0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20  nect)(sqlite3*, 
24bd0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
24be0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
24bf0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
24c00 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
24c10 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
24c20 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
24c30 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
24c40 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28  t (*xBestIndex)(
24c50 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
24c60 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64  Tab, sqlite3_ind
24c70 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74  ex_info*);.  int
24c80 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28   (*xDisconnect)(
24c90 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
24ca0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  Tab);.  int (*xD
24cb0 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f  estroy)(sqlite3_
24cc0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
24cd0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
24ce0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
24cf0 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  , sqlite3_vtab_c
24d00 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72  ursor **ppCursor
24d10 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  );.  int (*xClos
24d20 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e)(sqlite3_vtab_
24d30 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
24d40 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74  (*xFilter)(sqlit
24d50 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
24d60 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e   int idxNum, con
24d70 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c  st char *idxStr,
24d80 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
24d90 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74   int argc, sqlit
24da0 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29  e3_value **argv)
24db0 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29  ;.  int (*xNext)
24dc0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
24dd0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
24de0 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74  xEof)(sqlite3_vt
24df0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
24e00 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71  nt (*xColumn)(sq
24e10 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
24e20 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r*, sqlite3_cont
24e30 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ext*, int);.  in
24e40 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69  t (*xRowid)(sqli
24e50 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
24e60 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
24e70 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20  *pRowid);.  int 
24e80 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74  (*xUpdate)(sqlit
24e90 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20  e3_vtab *, int, 
24ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
24eb0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
24ec0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67  *);.  int (*xBeg
24ed0 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  in)(sqlite3_vtab
24ee0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
24ef0 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
24f00 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
24f10 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
24f20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
24f30 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  Tab);.  int (*xR
24f40 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33  ollback)(sqlite3
24f50 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
24f60 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63   int (*xFindFunc
24f70 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  tion)(sqlite3_vt
24f80 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e  ab *pVtab, int n
24f90 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Arg, const char 
24fa0 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20  *zName,.        
24fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
24fc0 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73  oid (**pxFunc)(s
24fd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
24fe0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
24ff0 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20  e**),.          
25000 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
25010 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69  d **ppArg);..  i
25020 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
25030 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
25040 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
25050 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
25060 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
25070 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
25080 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
25090 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74  ctures is used t
250a0 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d  o.** pass inform
250b0 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72  ation into and r
250c0 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79  eceive the reply
250d0 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49   from the xBestI
250e0 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ndex.** method o
250f0 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64  f an sqlite3_mod
25100 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73  ule.  The fields
25110 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
25120 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
25130 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
25140 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
25150 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
25160 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
25170 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
25180 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
25190 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  lds..**.** The a
251a0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
251b0 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
251c0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
251d0 6e 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  nts of the.** fo
251e0 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20  rm:.**.**       
251f0 20 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72    column OP expr
25200 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20  .**.** Where OP 
25210 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
25220 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
25230 3d 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74  =.  .** The part
25240 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20  icular operator 
25250 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
25260 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
25270 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  .  The index of 
25280 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74  the column is st
25290 6f 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e  ored in .** aCon
252a0 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d  straint[].iColum
252b0 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  n.  aConstraint[
252c0 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45  ].usable is TRUE
252d0 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20   if the.** expr 
252e0 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  on the right-han
252f0 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76  d side can be ev
25300 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75  aluated (and thu
25310 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  s the constraint
25320 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61  .** is usable) a
25330 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63  nd false if it c
25340 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  annot..**.** The
25350 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d   optimizer autom
25360 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73  atically inverts
25370 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f   terms of the fo
25380 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75  rm "expr OP colu
25390 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73  mn".** and makes
253a0 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63   other simplific
253b0 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48  ations to the WH
253c0 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e  ERE clause in an
253d0 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67   attempt to.** g
253e0 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45  et as many WHERE
253f0 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
25400 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77  to the form show
25410 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69  n above as possi
25420 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ble..** The aCon
25430 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
25440 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45  only reports WHE
25450 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
25460 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a  in the correct.*
25470 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65  * form that refe
25480 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75  r to the particu
25490 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
254a0 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e  e being queried.
254b0 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69  .**.** Informati
254c0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44  on about the ORD
254d0 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
254e0 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72  stored in aOrder
254f0 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65  By[]..** Each te
25500 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
25510 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
25520 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
25530 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
25540 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
25550 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
25560 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
25570 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
25580 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
25590 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
255a0 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
255b0 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
255c0 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
255d0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
255e0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
255f0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
25600 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
25610 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
25620 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
25630 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43   in argv.  If aC
25640 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
25650 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65  .omit.** is true
25660 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74  , then the const
25670 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64  raint is assumed
25680 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e   to be fully han
25690 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76  dled by the.** v
256a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
256b0 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20   is not checked 
256c0 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e  again by SQLite.
256d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75  .**.** The idxNu
256e0 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c  m and idxPtr val
256f0 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64  ues are recorded
25700 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f   and passed into
25710 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c   xFilter..** sql
25720 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75  ite3_free() is u
25730 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50  sed to free idxP
25740 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65  tr if needToFree
25750 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a  IdxPtr is true..
25760 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42  **.** The orderB
25770 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20  yConsumed means 
25780 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d  that output from
25790 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63   xFilter will oc
257a0 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f  cur in.** the co
257b0 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73  rrect order to s
257c0 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52  atisfy the ORDER
257d0 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68   BY clause so th
257e0 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a  at no separate.*
257f0 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69  * sorting step i
25800 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
25810 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43  * The estimatedC
25820 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20  ost value is an 
25830 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20  estimate of the 
25840 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68  cost of doing th
25850 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20  e.** particular 
25860 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20  lookup.  A full 
25870 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20  scan of a table 
25880 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73  with N entries s
25890 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20  hould have.** a 
258a0 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69  cost of N.  A bi
258b0 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61  nary search of a
258c0 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72   table of N entr
258d0 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20  ies should have 
258e0 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70  a.** cost of app
258f0 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e  roximately log(N
25900 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  )..*/.struct sql
25910 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
25920 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f  {.  /* Inputs */
25930 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69  .  int nConstrai
25940 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  nt;           /*
25950 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69   Number of entri
25960 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  es in aConstrain
25970 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  t */.  struct sq
25980 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
25990 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e  traint {.     in
259a0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
259b0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
259c0 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73  n on left-hand s
259d0 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e  ide of constrain
259e0 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  t */.     unsign
259f0 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20  ed char op;     
25a00 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e      /* Constrain
25a10 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20  t operator */.  
25a20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
25a30 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20   usable;     /* 
25a40 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e  True if this con
25a50 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c  straint is usabl
25a60 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54  e */.     int iT
25a70 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20  ermOffset;      
25a80 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
25a90 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e  rnally - xBestIn
25aa0 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72  dex should ignor
25ab0 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  e */.  } *aConst
25ac0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
25ad0 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48    /* Table of WH
25ae0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
25af0 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20  raints */.  int 
25b00 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  nOrderBy;       
25b10 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
25b20 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65   of terms in the
25b30 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
25b40 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
25b50 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72  ite3_index_order
25b60 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  by {.     int iC
25b70 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
25b80 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75      /* Column nu
25b90 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  mber */.     uns
25ba0 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b  igned char desc;
25bb0 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66         /* True f
25bc0 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20  or DESC.  False 
25bd0 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20  for ASC. */.  } 
25be0 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20  *aOrderBy;      
25bf0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20           /* The 
25c00 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
25c10 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73  */..  /* Outputs
25c20 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
25c30 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
25c40 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20  raint_usage {.  
25c50 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b    int argvIndex;
25c60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66             /* if
25c70 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20   >0, constraint 
25c80 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20  is part of argv 
25c90 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20  to xFilter */.  
25ca0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
25cb0 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f  omit;      /* Do
25cc0 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74   not code a test
25cd0 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72   for this constr
25ce0 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  aint */.  } *aCo
25cf0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20  nstraintUsage;. 
25d00 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20   int idxNum;    
25d10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
25d20 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64  umber used to id
25d30 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78  entify the index
25d40 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53   */.  char *idxS
25d50 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  tr;             
25d60 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73   /* String, poss
25d70 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  ibly obtained fr
25d80 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
25d90 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54  c */.  int needT
25da0 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20  oFreeIdxStr;    
25db0 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72    /* Free idxStr
25dc0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
25dd0 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f  ree() if true */
25de0 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f  .  int orderByCo
25df0 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a  nsumed;       /*
25e00 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20   True if output 
25e10 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72  is already order
25e20 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65  ed */.  double e
25e30 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20  stimatedCost;   
25e40 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20     /* Estimated 
25e50 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68  cost of using th
25e60 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23  is index */.};.#
25e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
25e80 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
25e90 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  Q    2.#define S
25ea0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
25eb0 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23  TRAINT_GT    4.#
25ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
25ed0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
25ee0 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53  E    8.#define S
25ef0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
25f00 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a  TRAINT_LT    16.
25f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
25f20 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
25f30 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  GE    32.#define
25f40 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
25f50 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36  NSTRAINT_MATCH 6
25f60 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  4../*.** This ro
25f70 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f  utine is used to
25f80 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
25f90 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68  module name with
25fa0 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f   an SQLite.** co
25fb0 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c  nnection.  Modul
25fc0 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
25fd0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
25fe0 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a  e creating new.*
25ff0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
26000 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20   on the module, 
26010 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  or before using 
26020 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74  preexisting virt
26030 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66  ual.** tables of
26040 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a   the module..*/.
26050 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
26060 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
26070 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26080 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
26090 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
260a0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
260b0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
260c0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
260d0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
260e0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
260f0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
26100 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
26110 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
26120 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
26130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26140 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
26150 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
26160 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a  xConnect */.);..
26170 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  /*.** This routi
26180 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  ne is identical 
26190 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  to the sqlite3_c
261a0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d  reate_module() m
261b0 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20  ethod above,.** 
261c0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
261d0 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74  llows a destruct
261e0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  or function to b
261f0 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20  e specified. It 
26200 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20  is.** even more 
26210 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61  experimental tha
26220 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68  n the rest of th
26230 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
26240 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   API..*/.int sql
26250 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
26260 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
26270 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26280 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
26290 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
262a0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
262b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
262c0 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
262d0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
262e0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
262f0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
26300 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *,    /* Method
26310 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
26320 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
26330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26340 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
26350 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
26360 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
26370 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
26380 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
26390 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
263a0 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
263b0 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
263c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
263d0 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
263e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
263f0 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
26400 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
26410 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ar instance of t
26420 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
26430 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
26440 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
26450 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
26460 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
26470 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
26480 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f  .   The.** purpo
26490 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
264a0 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
264b0 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
264c0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f  s that are commo
264d0 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  n.** to all modu
264e0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
264f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
26500 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
26510 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
26520 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
26530 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
26540 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
26550 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
26560 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  () to zErrMsg.  
26570 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
26580 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
26590 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
265a0 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
265b0 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
265c0 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69  e3_free().** pri
265d0 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
265e0 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
265f0 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20  zErrMsg.  After 
26600 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
26610 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
26620 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
26630 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
26640 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
26650 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
26660 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
26670 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
26680 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
26690 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
266a0 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20  .  Note.** that 
266b0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
266c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72  ) and sqlite3_fr
266d0 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e  ee() are used on
266e0 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
266f0 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74  ld.** since virt
26700 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63  ual tables are c
26710 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e  ommonly implemen
26720 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20  ted in loadable 
26730 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68  extensions which
26740 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  .** do not have 
26750 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65  access to sqlite
26760 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71  3MPrintf() or sq
26770 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a  lite3Free()..*/.
26780 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
26790 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
267a0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
267b0 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
267c0 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
267d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
267e0 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
267f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26800 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
26810 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ally */.  char *
26820 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
26830 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
26840 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
26850 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
26860 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
26870 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
26880 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
26890 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
268a0 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
268b0 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64  };../* Every mod
268c0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
268d0 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
268e0 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
268f0 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
26900 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72   to describe cur
26910 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20  sors that point 
26920 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  into the virtual
26930 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75   table and are u
26940 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74  sed.** to loop t
26950 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75  hrough the virtu
26960 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f  al table.  Curso
26970 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  rs are created u
26980 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65  sing the.** xOpe
26990 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  n method of the 
269a0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f  module.  Each mo
269b0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
269c0 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a  ion will define.
269d0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
269e0 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63  f a cursor struc
269f0 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73  ture to suit its
26a00 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a   own needs..**.*
26a10 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73  * This superclas
26a20 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65  s exists in orde
26a30 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c  r to define fiel
26a40 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72  ds of the cursor
26a50 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d   that.** are com
26a60 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65  mon to all imple
26a70 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73  mentations..*/.s
26a80 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
26a90 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71  ab_cursor {.  sq
26aa0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
26ab0 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75  b;      /* Virtu
26ac0 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73  al table of this
26ad0 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20   cursor */.  /* 
26ae0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
26af0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
26b00 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
26b10 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
26b20 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
26b30 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20  The xCreate and 
26b40 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73  xConnect methods
26b50 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65   of a module use
26b60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
26b70 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65  PI.** to declare
26b80 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65   the format (the
26b90 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74   names and datat
26ba0 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ypes of the colu
26bb0 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76  mns) of.** the v
26bc0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68  irtual tables th
26bd0 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f  ey implement..*/
26be0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63  .int sqlite3_dec
26bf0 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
26c00 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
26c10 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a  zCreateTable);..
26c20 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  /*.** Virtual ta
26c30 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
26c40 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
26c50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
26c60 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
26c70 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63  ng the xFindFunc
26c80 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75  tion method.  Bu
26c90 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
26ca0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
26cb0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
26cc0 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
26cd0 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  e overloaded..**
26ce0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b  .** This API mak
26cf0 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
26d00 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
26d10 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
26d20 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
26d30 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
26d40 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
26d50 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
26d60 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
26d70 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
26d80 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
26d90 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
26da0 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  eated.  The impl
26db0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
26dc0 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
26dd0 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20  n always causes 
26de0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  an exception to 
26df0 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a  be thrown.  So.*
26e00 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  * the new functi
26e10 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66  on is not good f
26e20 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69  or anything by i
26e30 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79  tself.  Its only
26e40 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74  .** purpose is t
26e50 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c  o be a place-hol
26e60 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
26e70 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
26e80 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61  ded.** by virtua
26e90 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  l tables..**.** 
26ea0 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20  This API should 
26eb0 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61  be considered pa
26ec0 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  rt of the virtua
26ed0 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
26ee0 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65  e,.** which is e
26ef0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
26f00 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
26f10 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
26f20 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74  3_overload_funct
26f30 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  ion(sqlite3*, co
26f40 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e  nst char *zFuncN
26f50 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a  ame, int nArg);.
26f60 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
26f70 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
26f80 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
26f90 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ism defined abov
26fa0 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f  e (back up.** to
26fb0 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72   a comment remar
26fc0 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f  kably similar to
26fd0 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75   this one) is cu
26fe0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
26ff0 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
27000 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
27010 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
27020 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
27030 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
27040 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
27050 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
27060 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
27070 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
27080 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
27090 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
270a0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
270b0 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
270c0 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
270d0 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
270e0 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
270f0 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
27100 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
27110 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  .**.****** EXPER
27120 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
27130 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
27140 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
27150 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a  *********.*/../*
27160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20  .** CAPI3REF: A 
27170 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65  Handle To An Ope
27180 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 30 7d 0a  n BLOB {F17800}.
27190 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
271a0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
271b0 6e 67 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ng opaque struct
271c0 75 72 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a  ure is used to .
271d0 2a 2a 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20  ** represent an 
271e0 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20  blob-handle.  A 
271f0 62 6c 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63  blob-handle is c
27200 72 65 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71  reated by.** [sq
27210 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
27220 29 5d 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64  )] and destroyed
27230 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
27240 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54  b_close()]..** T
27250 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
27260 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
27270 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
27280 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
27290 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
272a0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
272b0 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
272c0 20 6f 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a   of the blob..**
272d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
272e0 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
272f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
27300 65 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  e size of the.**
27310 20 62 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a   blob in bytes..
27320 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
27330 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73  t sqlite3_blob s
27340 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a  qlite3_blob;../*
27350 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
27360 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e  en A BLOB For In
27370 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46  cremental I/O {F
27380 31 37 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  17810}.**.** {F1
27390 37 38 31 31 7d 20 54 68 69 73 20 69 6e 74 65 72  7811} This inter
273a0 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 68 61  faces opens a ha
273b0 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62  ndle to the blob
273c0 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
273d0 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e  ow iRow,, column
273e0 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
273f0 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
27400 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
27410 68 65 72 20 77 6f 72 64 73 2c 20 20 74 68 65 20  her words,  the 
27420 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 74 20 77  same blob that w
27430 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64  ould be selected
27440 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
27450 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
27460 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
27470 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77  zTable WHERE row
27480 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  id = iRow;.** </
27490 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  pre> {END}.**.**
274a0 20 7b 46 31 37 38 31 32 7d 20 49 66 20 74 68 65   {F17812} If the
274b0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
274c0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
274d0 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64  e blob is opened
274e0 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e   for .** read an
274f0 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20  d write access. 
27500 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74  If it is zero, t
27510 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65  he blob is opene
27520 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61  d for read .** a
27530 63 63 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ccess. {END}.**.
27540 2a 2a 20 7b 46 31 37 38 31 33 7d 20 4f 6e 20 73  ** {F17813} On s
27550 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
27560 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
27570 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20  and the new .** 
27580 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
27590 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20  blob handle] is 
275a0 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c  written to *ppBl
275b0 6f 62 2e 20 0a 2a 2a 20 7b 46 31 37 38 31 34 7d  ob. .** {F17814}
275c0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
275d0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
275e0 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79  rned and .** any
275f0 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74   value written t
27600 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64  o *ppBlob should
27610 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
27620 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 7b  the caller..** {
27630 46 31 37 38 31 35 7d 20 54 68 69 73 20 66 75 6e  F17815} This fun
27640 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64  ction sets the d
27650 61 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65  atabase-handle e
27660 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
27670 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
27680 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
27690 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
276a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
276b0 29 5d 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 65 20  )]..** <todo>We 
276c0 73 68 6f 75 6c 64 20 67 6f 20 74 68 72 6f 75 67  should go throug
276d0 68 20 61 6e 64 20 6d 61 72 6b 20 61 6c 6c 20 69  h and mark all i
276e0 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 62  nterfaces that b
276f0 65 68 61 76 65 20 74 68 69 73 0a 2a 2a 20 77 61  ehave this.** wa
27700 79 20 77 69 74 68 20 61 20 73 69 6d 69 6c 61 72  y with a similar
27710 20 73 74 61 74 65 6d 65 6e 74 3c 2f 74 6f 64 6f   statement</todo
27720 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
27730 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
27740 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
27750 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
27760 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
27770 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
27780 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
27790 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
277a0 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
277b0 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
277c0 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
277d0 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20  I3REF:  Close A 
277e0 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 46 31 37  BLOB Handle {F17
277f0 38 33 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  830}.**.** Close
27800 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65   an open [sqlite
27810 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61  3_blob | blob ha
27820 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ndle]..**.** {F1
27830 37 38 33 31 7d 20 43 6c 6f 73 69 6e 67 20 61 20  7831} Closing a 
27840 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65  BLOB shall cause
27850 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61   the current tra
27860 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d  nsaction to comm
27870 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61  it.** if there a
27880 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42  re no other BLOB
27890 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72  s, no pending pr
278a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
278b0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61  s, and the.** da
278c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
278d0 6e 20 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d  n is in autocomm
278e0 69 74 20 6d 6f 64 65 2e 0a 2a 2a 20 7b 46 31 37  it mode..** {F17
278f0 38 33 32 7d 20 49 66 20 61 6e 79 20 77 72 69 74  832} If any writ
27900 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20  es were made to 
27910 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d  the BLOB, they m
27920 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20  ight be held in 
27930 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74  cache.** until t
27940 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69  he close operati
27950 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20  on if they will 
27960 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c  fit. {END}.** Cl
27970 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f  osing the BLOB o
27980 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20  ften forces the 
27990 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74  changes.** out t
279a0 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66  o disk and so if
279b0 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20   any I/O errors 
279c0 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c  occur, they will
279d0 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a   likely occur.**
279e0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
279f0 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  n the BLOB is cl
27a00 6f 73 65 64 2e 20 20 7b 46 31 37 38 33 33 7d 20  osed.  {F17833} 
27a10 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20  Any errors that 
27a20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20  occur during.** 
27a30 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f  closing are repo
27a40 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65  rted as a non-ze
27a50 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e  ro return value.
27a60 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 39 7d 20  .**.** {F17839} 
27a70 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  The BLOB is clos
27a80 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c  ed unconditional
27a90 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69  ly.  Even if thi
27aa0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
27ab0 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f  s.** an error co
27ac0 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20  de, the BLOB is 
27ad0 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2f  still closed..*/
27ae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
27af0 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f  b_close(sqlite3_
27b00 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
27b10 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75 72  CAPI3REF:  Retur
27b20 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e  n The Size Of An
27b30 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38   Open BLOB {F178
27b40 30 35 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 38 30  05}.**.** {F1680
27b50 36 7d 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  6} Return the si
27b60 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74  ze in bytes of t
27b70 68 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62  he blob accessib
27b80 6c 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20  le via the open 
27b90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
27ba0 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
27bb0 20 70 61 73 73 65 64 20 61 73 20 61 6e 20 61 72   passed as an ar
27bc0 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73  gument..*/.int s
27bd0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
27be0 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  s(sqlite3_blob *
27bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27c00 45 46 3a 20 20 52 65 61 64 20 44 61 74 61 20 46  EF:  Read Data F
27c10 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  rom A BLOB Incre
27c20 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 37 38 35 30  mentally {F17850
27c30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  }.**.** This fun
27c40 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ction is used to
27c50 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20   read data from 
27c60 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c  an open .** [sql
27c70 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
27c80 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20  -handle] into a 
27c90 63 61 6c 6c 65 72 20 73 75 70 70 6c 69 65 64 20  caller supplied 
27ca0 62 75 66 66 65 72 2e 0a 2a 2a 20 7b 46 31 37 38  buffer..** {F178
27cb0 35 31 7d 20 6e 20 62 79 74 65 73 20 6f 66 20 64  51} n bytes of d
27cc0 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69  ata are copied i
27cd0 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20  nto buffer.** z 
27ce0 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c  from the open bl
27cf0 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  ob, starting at 
27d00 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
27d10 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35 32 7d 20 49  **.** {F17852} I
27d20 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
27d30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20   is less than n 
27d40 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
27d50 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20  nd of the blob, 
27d60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
27d70 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
27d80 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
27d90 61 64 2e 20 20 7b 46 31 37 38 35 33 7d 20 49 66  ad.  {F17853} If
27da0 20 6e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   n is.** less th
27db0 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
27dc0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
27dd0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
27de0 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s read..**.** {F
27df0 31 37 38 35 34 7d 20 4f 6e 20 73 75 63 63 65 73  17854} On succes
27e00 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  s, SQLITE_OK is 
27e10 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77  returned. Otherw
27e20 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c  ise, an .** [SQL
27e30 49 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69  ITE_ERROR | SQLi
27e40 74 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  te error code] o
27e50 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
27e60 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
27e70 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
27e80 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
27e90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
27ea0 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f  ob_read(sqlite3_
27eb0 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c  blob *, void *z,
27ec0 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
27ed0 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
27ee0 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 61  I3REF:  Write Da
27ef0 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49  ta Into A BLOB I
27f00 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31  ncrementally {F1
27f10 37 38 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7870}.**.** This
27f20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
27f30 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
27f40 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a  into an open .**
27f50 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
27f60 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72   blob-handle] fr
27f70 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69  om a user suppli
27f80 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 7b 46  ed buffer..** {F
27f90 31 37 38 37 31 7d 20 6e 20 62 79 74 65 73 20 6f  17871} n bytes o
27fa0 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
27fb0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65  d from the buffe
27fc0 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  r.** pointed to 
27fd0 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70  by z into the op
27fe0 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
27ff0 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
28000 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  set..**.** {F178
28010 37 32 7d 20 49 66 20 74 68 65 20 5b 73 71 6c 69  72} If the [sqli
28020 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
28030 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
28040 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
28050 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  ment.** was not 
28060 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69  opened for writi
28070 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61  ng (the flags pa
28080 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
28090 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
280a0 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20  .*** was zero), 
280b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
280c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45  turns [SQLITE_RE
280d0 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ADONLY]..**.** {
280e0 46 31 37 38 37 33 7d 20 54 68 69 73 20 66 75 6e  F17873} This fun
280f0 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d  ction may only m
28100 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e  odify the conten
28110 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 3b 20  ts of the blob; 
28120 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
28130 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73  sible to increas
28140 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
28150 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20  blob using this 
28160 41 50 49 2e 0a 2a 2a 20 7b 46 31 37 38 37 34 7d  API..** {F17874}
28170 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73   If offset iOffs
28180 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
28190 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  n bytes from the
281a0 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62   end of the blob
281b0 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  , .** [SQLITE_ER
281c0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
281d0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
281e0 77 72 69 74 74 65 6e 2e 20 20 7b 46 31 37 38 37  written.  {F1787
281f0 35 7d 20 49 66 20 6e 20 69 73 0a 2a 2a 20 6c 65  5} If n is.** le
28200 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
28210 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
28220 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
28230 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
28240 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 36 7d 20 4f  **.** {F17876} O
28250 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
28260 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
28270 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20  . Otherwise, an 
28280 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
28290 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72  R | SQLite error
282a0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
282b0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
282c0 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72  AD | extended er
282d0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
282e0 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  urned..*/.int sq
282f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
28300 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
28310 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
28320 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
28330 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
28340 33 52 45 46 3a 20 20 56 69 72 74 75 61 6c 20 46  3REF:  Virtual F
28350 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
28360 74 73 20 7b 46 31 31 32 30 30 7d 0a 2a 2a 0a 2a  ts {F11200}.**.*
28370 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65  * A virtual file
28380 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73 20  system (VFS) is 
28390 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
283a0 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20   object.** that 
283b0 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69  SQLite uses to i
283c0 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20  nteract.** with 
283d0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
283e0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
283f0 20 20 4d 6f 73 74 20 62 75 69 6c 64 73 20 63 6f    Most builds co
28400 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e  me with a.** sin
28410 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  gle default VFS 
28420 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
28430 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74  ate for the host
28440 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65   computer..** Ne
28450 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72  w VFSes can be r
28460 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78  egistered and ex
28470 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e  isting VFSes can
28480 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64   be unregistered
28490 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ..** The followi
284a0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ng interfaces ar
284b0 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a  e provided..**.*
284c0 2a 20 7b 46 31 31 32 30 31 7d 20 54 68 65 20 73  * {F11201} The s
284d0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
284e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
284f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
28500 20 0a 2a 2a 20 61 20 56 46 53 20 67 69 76 65 6e   .** a VFS given
28510 20 69 74 73 20 6e 61 6d 65 2e 20 20 7b 46 31 31   its name.  {F11
28520 32 30 32 7d 20 4e 61 6d 65 73 20 61 72 65 20 63  202} Names are c
28530 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a  ase sensitive..*
28540 2a 20 7b 46 31 31 32 30 33 7d 20 4e 61 6d 65 73  * {F11203} Names
28550 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
28560 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
28570 67 73 2e 0a 2a 2a 20 7b 46 31 31 32 30 34 7d 20  gs..** {F11204} 
28580 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
28590 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20  atch, a NULL.** 
285a0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
285b0 6e 65 64 2e 20 7b 46 31 31 32 30 35 7d 20 49 66  ned. {F11205} If
285c0 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c   zVfsName is NUL
285d0 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  L then the defau
285e0 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 20 72 65  lt .** VFS is re
285f0 74 75 72 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  turned. {END}.**
28600 0a 2a 2a 20 7b 46 31 31 32 31 30 7d 20 4e 65 77  .** {F11210} New
28610 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73   VFSes are regis
28620 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74  tered with sqlit
28630 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
28640 29 2e 0a 2a 2a 20 7b 46 31 31 32 31 31 7d 20 45  )..** {F11211} E
28650 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f  ach new VFS beco
28660 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  mes the default 
28670 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44  VFS if the makeD
28680 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e  flt flag is set.
28690 0a 2a 2a 20 7b 46 31 31 32 31 32 7d 20 54 68 65  .** {F11212} The
286a0 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65   same VFS can be
286b0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
286c0 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f  iple times witho
286d0 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 7b 46  ut injury..** {F
286e0 31 31 32 31 33 7d 20 54 6f 20 6d 61 6b 65 20 61  11213} To make a
286f0 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69  n existing VFS i
28700 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20  nto the default 
28710 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74  VFS, register it
28720 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74   again.** with t
28730 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
28740 20 73 65 74 2e 20 7b 55 31 31 32 31 34 7d 20 49   set. {U11214} I
28750 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20  f two different 
28760 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a  VFSes with the.*
28770 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  * same name are 
28780 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20  registered, the 
28790 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
287a0 66 69 6e 65 64 2e 20 20 7b 55 31 31 32 31 35 7d  fined.  {U11215}
287b0 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
287c0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
287d0 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
287e0 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
287f0 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
28800 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
28810 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a  undefined..** .*
28820 2a 20 7b 46 31 31 32 32 30 7d 20 55 6e 72 65 67  * {F11220} Unreg
28830 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
28840 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
28850 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
28860 74 65 72 66 61 63 65 2e 0a 2a 2a 20 7b 46 31 31  terface..** {F11
28870 32 32 31 7d 20 49 66 20 74 68 65 20 64 65 66 61  221} If the defa
28880 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67  ult VFS is unreg
28890 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72  istered, another
288a0 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61   VFS is chosen a
288b0 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  s.** the default
288c0 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f  .  The choice fo
288d0 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73  r the new VFS is
288e0 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73   arbitrary..*/.s
288f0 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
28900 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
28910 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
28920 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
28930 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
28940 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
28950 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
28960 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
28970 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
28980 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
28990 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 46 31  REF: Mutexes {F1
289a0 37 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7000}.**.** The 
289b0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
289c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
289d0 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79  for thread.** sy
289e0 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20  nchronization.  
289f0 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
28a00 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
28a10 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
28a20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
28a30 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
28a40 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
28a50 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
28a60 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
28a70 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
28a80 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
28a90 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
28aa0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
28ab0 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74 68 65 73 65  ons .** of these
28ac0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
28ad0 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65    An appropriate
28ae0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
28af0 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61  ** is selected a
28b00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20  utomatically at 
28b10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54  compile-time.  T
28b20 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
28b30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
28b40 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  are available in
28b50 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
28b60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
28b70 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
28b80 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_OS2.** <li> 
28b90 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50    SQLITE_MUTEX_P
28ba0 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20  THREAD.** <li>  
28bb0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
28bc0 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  2.** <li>   SQLI
28bd0 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a  TE_MUTEX_NOOP.**
28be0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
28bf0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
28c00 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  OP implementatio
28c10 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f  n is a set of ro
28c20 75 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20  utines .** that 
28c30 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63  does no real loc
28c40 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72  king and is appr
28c50 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
28c60 69 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d  in .** a single-
28c70 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
28c80 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54  tion.  The SQLIT
28c90 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20  E_MUTEX_OS2,.** 
28ca0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
28cb0 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45  READ, and SQLITE
28cc0 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65  _MUTEX_W32 imple
28cd0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
28ce0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  e appropriate fo
28cf0 72 20 75 73 65 20 6f 6e 20 6f 73 2f 32 2c 20 75  r use on os/2, u
28d00 6e 69 78 2c 20 61 6e 64 20 77 69 6e 64 6f 77 73  nix, and windows
28d10 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 53 51 4c 69  ..** .** If SQLi
28d20 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
28d30 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d  ith the SQLITE_M
28d40 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70  UTEX_APPDEF prep
28d50 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72  rocessor.** macr
28d60 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20  o defined (with 
28d70 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  "-DSQLITE_MUTEX_
28d80 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e  APPDEF=1"), then
28d90 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
28da0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
28db0 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
28dc0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 0a 2a   library.  The.*
28dd0 2a 20 6d 75 74 65 78 20 69 6e 74 65 72 66 61 63  * mutex interfac
28de0 65 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  e routines defin
28df0 65 64 20 68 65 72 65 20 62 65 63 6f 6d 65 20 65  ed here become e
28e00 78 74 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72  xternal.** refer
28e10 65 6e 63 65 73 20 69 6e 20 74 68 65 20 53 51 4c  ences in the SQL
28e20 69 74 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20  ite library for 
28e30 77 68 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61  which implementa
28e40 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65  tions.** must be
28e50 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
28e60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
28e70 68 69 73 20 66 61 63 69 6c 69 74 79 20 61 6c 6c  his facility all
28e80 6f 77 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63  ows an.** applic
28e90 61 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73  ation that links
28ea0 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20   against SQLite 
28eb0 74 6f 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f  to provide its o
28ec0 77 6e 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  wn mutex.** impl
28ed0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f  ementation witho
28ee0 75 74 20 68 61 76 69 6e 67 20 74 6f 20 6d 6f 64  ut having to mod
28ef0 69 66 79 20 74 68 65 20 53 51 4c 69 74 65 20 63  ify the SQLite c
28f00 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30  ore..**.** {F170
28f10 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  11} The sqlite3_
28f20 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f  mutex_alloc() ro
28f30 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20  utine allocates 
28f40 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61  a new.** mutex a
28f50 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
28f60 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b 46 31 37  nter to it. {F17
28f70 30 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72  012} If it retur
28f80 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20  ns NULL.** that 
28f90 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74  means that a mut
28fa0 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ex could not be 
28fb0 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 46 31 37 30  allocated. {F170
28fc0 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  13} SQLite.** wi
28fd0 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74  ll unwind its st
28fe0 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ack and return a
28ff0 6e 20 65 72 72 6f 72 2e 20 7b 46 31 37 30 31 34  n error. {F17014
29000 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  } The argument.*
29010 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
29020 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
29030 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
29040 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
29050 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
29060 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
29070 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
29080 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
29090 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
290a0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
290b0 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
290c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
290d0 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
290e0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
290f0 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c  TATIC_MEM2.** <l
29100 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
29110 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20  _STATIC_PRNG.** 
29120 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
29130 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a  EX_STATIC_LRU.**
29140 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a   </ul> {END}.**.
29150 2a 2a 20 7b 46 31 37 30 31 35 7d 20 54 68 65 20  ** {F17015} The 
29160 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61  first two consta
29170 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69 74 65  nts cause sqlite
29180 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
29190 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e  to create.** a n
291a0 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e  ew mutex.  The n
291b0 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75  ew mutex is recu
291c0 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54  rsive when SQLIT
291d0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
291e0 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74  E.** is used but
291f0 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79   not necessarily
29200 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f   so when SQLITE_
29210 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73  MUTEX_FAST is us
29220 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65  ed. {END}.** The
29230 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
29240 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
29250 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69  eed to make a di
29260 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
29270 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  ween SQLITE_MUTE
29280 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20  X_RECURSIVE and 
29290 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
292a0 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20  T if it does.** 
292b0 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 7b 46  not want to.  {F
292c0 31 37 30 31 36 7d 20 42 75 74 20 53 51 4c 69 74  17016} But SQLit
292d0 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75  e will only requ
292e0 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20  est a recursive 
292f0 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65  mutex in.** case
29300 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c  s where it reall
29310 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45  y needs one.  {E
29320 4e 44 7d 20 49 66 20 61 20 66 61 73 74 65 72 20  ND} If a faster 
29330 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75  non-recursive mu
29340 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
29350 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
29360 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70  le on the host p
29370 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74  latform, the mut
29380 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ex subsystem.** 
29390 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63  might return suc
293a0 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73  h a mutex in res
293b0 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f  ponse to SQLITE_
293c0 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a  MUTEX_FAST..**.*
293d0 2a 20 7b 46 31 37 30 31 37 7d 20 54 68 65 20 6f  * {F17017} The o
293e0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
293f0 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
29400 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
29410 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
29420 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
29430 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
29440 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20  g mutex. {END}  
29450 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 65  Four static mute
29460 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  xes are.** used 
29470 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  by the current v
29480 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
29490 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
294a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
294b0 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  may add addition
294c0 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
294d0 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78  s.  Static mutex
294e0 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72  es are for inter
294f0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
29500 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  Lite only.  Appl
29510 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
29520 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73  e SQLite mutexes
29530 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f   should.** use o
29540 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20  nly the dynamic 
29550 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64  mutexes returned
29560 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   by SQLITE_MUTEX
29570 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49  _FAST or.** SQLI
29580 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
29590 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31  VE..**.** {F1701
295a0 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 66 20  8} Note that if 
295b0 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d  one of the dynam
295c0 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74  ic mutex paramet
295d0 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45  ers (SQLITE_MUTE
295e0 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c  X_FAST.** or SQL
295f0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
29600 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68 65  IVE) is used the
29610 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  n sqlite3_mutex_
29620 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72  alloc().** retur
29630 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d  ns a different m
29640 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61  utex on every ca
29650 6c 6c 2e 20 20 7b 46 31 37 30 33 34 7d 20 42 75  ll.  {F17034} Bu
29660 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
29670 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73   .** mutex types
29680 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
29690 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
296a0 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
296b0 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
296c0 74 79 70 65 20 6e 75 6d 62 65 72 2e 20 7b 45 4e  type number. {EN
296d0 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 39  D}.**.** {F17019
296e0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
296f0 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
29700 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
29710 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
29720 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
29730 20 6d 75 74 65 78 2e 20 7b 46 31 37 30 32 30 7d   mutex. {F17020}
29740 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66   SQLite is caref
29750 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ul to deallocate
29760 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69   every.** dynami
29770 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20  c mutex that it 
29780 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 55 31 37 30  allocates. {U170
29790 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20  21} The dynamic 
297a0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
297b0 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77   be in .** use w
297c0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
297d0 6c 6c 6f 63 61 74 65 64 2e 20 7b 55 31 37 30 32  llocated. {U1702
297e0 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  2} Attempting to
297f0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74   deallocate a st
29800 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65  atic.** mutex re
29810 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
29820 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 46 31  ed behavior. {F1
29830 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76  7023} SQLite nev
29840 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
29850 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
29860 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
29870 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
29880 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69  enter() and sqli
29890 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
298a0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
298b0 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d  .** to enter a m
298c0 75 74 65 78 2e 20 7b 46 31 37 30 32 34 7d 20 49  utex. {F17024} I
298d0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
298e0 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68   is already with
298f0 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a  in the mutex,.**
29900 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
29910 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63  nter() will bloc
29920 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  k and sqlite3_mu
29930 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72  tex_try() will r
29940 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
29950 42 55 53 59 2e 20 7b 46 31 37 30 32 35 7d 20 20  BUSY. {F17025}  
29960 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
29970 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63  x_try() interfac
29980 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
29990 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  _OK.** upon succ
299a0 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b  essful entry.  {
299b0 46 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20  F17026} Mutexes 
299c0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
299d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
299e0 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65  CURSIVE can be e
299f0 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  ntered multiple 
29a00 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d  times by the sam
29a10 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 46 31  e thread..** {F1
29a20 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61  7027} In such ca
29a30 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65  ses the,.** mute
29a40 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64  x must be exited
29a50 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72   an equal number
29a60 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65   of times before
29a70 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
29a80 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b  ** can enter.  {
29a90 55 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73  U17028} If the s
29aa0 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73  ame thread tries
29ab0 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74   to enter any ot
29ac0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d  her.** kind of m
29ad0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f  utex more than o
29ae0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f  nce, the behavio
29af0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
29b00 2a 2a 20 7b 46 31 37 30 32 39 7d 20 53 51 4c 69  ** {F17029} SQLi
29b10 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
29b20 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
29b30 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
29b40 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
29b50 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 6f  . {END}.**.** So
29b60 6d 65 20 73 79 73 74 65 6d 73 20 28 65 78 3a 20  me systems (ex: 
29b70 77 69 6e 64 6f 77 73 39 35 29 20 64 6f 20 6e 6f  windows95) do no
29b80 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
29b90 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a  implemented by.*
29ba0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
29bb0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
29bc0 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
29bd0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
29be0 6c 6c 0a 2a 2a 20 61 6c 77 61 79 73 20 72 65 74  ll.** always ret
29bf0 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
29c00 20 20 7b 46 31 37 30 33 30 7d 20 54 68 65 20 53    {F17030} The S
29c10 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20  QLite core only 
29c20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c  ever uses.** sql
29c30 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
29c40 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74   as an optimizat
29c50 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61  ion so this is a
29c60 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69  cceptable behavi
29c70 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  or. {END}.**.** 
29c80 7b 46 31 37 30 33 31 7d 20 54 68 65 20 73 71 6c  {F17031} The sql
29c90 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
29ca0 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73  () routine exits
29cb0 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61   a mutex that wa
29cc0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
29cd0 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73  entered by the s
29ce0 61 6d 65 20 74 68 72 65 61 64 2e 20 20 7b 55 31  ame thread.  {U1
29cf0 37 30 33 32 7d 20 54 68 65 20 62 65 68 61 76 69  7032} The behavi
29d00 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
29d10 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ed if the mutex 
29d20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
29d30 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a   entered by the.
29d40 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  ** calling threa
29d50 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72  d or is not curr
29d60 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e  ently allocated.
29d70 20 20 7b 46 31 37 30 33 33 7d 20 53 51 4c 69 74    {F17033} SQLit
29d80 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20  e will.** never 
29d90 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d  do either. {END}
29da0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29db0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
29dc0 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  held()] and [sql
29dd0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
29de0 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ld()]..*/.sqlite
29df0 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33  3_mutex *sqlite3
29e00 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74  _mutex_alloc(int
29e10 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29e20 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74  mutex_free(sqlit
29e30 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64  e3_mutex*);.void
29e40 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
29e50 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74  nter(sqlite3_mut
29e60 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ex*);.int sqlite
29e70 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69  3_mutex_try(sqli
29e80 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69  te3_mutex*);.voi
29e90 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
29ea0 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75  leave(sqlite3_mu
29eb0 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
29ec0 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65  PI3REF: Mutex Ve
29ed0 72 69 66 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  rifcation Routin
29ee0 65 73 20 7b 46 31 37 30 38 30 7d 0a 2a 2a 0a 2a  es {F17080}.**.*
29ef0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
29f00 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73  tex_held() and s
29f10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
29f20 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a  held() routines.
29f30 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ** are intended 
29f40 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
29f50 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
29f60 74 73 2e 20 7b 46 31 37 30 38 31 7d 20 54 68 65  ts. {F17081} The
29f70 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20   SQLite core.** 
29f80 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65  never uses these
29f90 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74   routines except
29fa0 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72   inside an asser
29fb0 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74  t() and applicat
29fc0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69  ions.** are advi
29fd0 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68  sed to follow th
29fe0 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f  e lead of the co
29ff0 72 65 2e 20 20 7b 46 31 37 30 38 32 7d 20 54 68  re.  {F17082} Th
2a000 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70  e core only.** p
2a010 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e  rovides implemen
2a020 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73  tations for thes
2a030 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20  e routines when 
2a040 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  it is compiled.*
2a050 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  * with the SQLIT
2a060 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b  E_DEBUG flag.  {
2a070 55 31 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c  U17087} External
2a080 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
2a090 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e  ations.** are on
2a0a0 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70  ly required to p
2a0b0 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75  rovide these rou
2a0c0 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f  tines if SQLITE_
2a0d0 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69  DEBUG is.** defi
2a0e0 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55  ned and if NDEBU
2a0f0 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64  G is not defined
2a100 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 38 33 7d  ..**.** {F17083}
2a110 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a120 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72  should return tr
2a130 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ue if the mutex 
2a140 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e  in their argumen
2a150 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20  t.** is held or 
2a160 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63  not held, respec
2a170 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63  tively, by the c
2a180 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 20 7b  alling thread. {
2a190 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30  END}.**.** {X170
2a1a0 38 34 7d 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  84} The implemen
2a1b0 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65  tation is not re
2a1c0 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
2a1d0 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  ed versions of t
2a1e0 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hese.** routines
2a1f0 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77   that actually w
2a200 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  ork..** If the i
2a210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
2a220 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77  es not provide w
2a230 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f  orking.** versio
2a240 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ns of these rout
2a250 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20  ines, it should 
2a260 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65  at least provide
2a270 20 73 74 75 62 73 0a 2a 2a 20 74 68 61 74 20 61   stubs.** that a
2a280 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 72 75  lways return tru
2a290 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f  e so that one do
2a2a0 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69  es not get spuri
2a2b0 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e  ous.** assertion
2a2c0 20 66 61 69 6c 75 72 65 73 2e 20 7b 45 4e 44 7d   failures. {END}
2a2d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 38 35 7d 20  .**.** {F17085} 
2a2e0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
2a2f0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
2a300 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c  _held() is a NUL
2a310 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
2a320 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68  * the routine sh
2a330 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20  ould return 1.  
2a340 7b 45 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73  {END} This seems
2a350 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69   counter-intuiti
2a360 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61  ve since.** clea
2a370 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61  rly the mutex ca
2a380 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20  nnot be held if 
2a390 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  it does not exis
2a3a0 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74  t.  But the.** t
2a3b0 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75  he reason the mu
2a3c0 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69  tex does not exi
2a3d0 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68  st is because th
2a3e0 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a  e build is not.*
2a3f0 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e  * using mutexes.
2a400 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20    And we do not 
2a410 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28  want the assert(
2a420 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
2a430 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
2a440 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
2a450 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e   to fail, so a n
2a460 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69  on-zero return i
2a470 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72  s.** the appropr
2a480 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f  iate thing to do
2a490 2e 20 20 7b 46 31 37 30 38 36 7d 20 54 68 65 20  .  {F17086} The 
2a4a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
2a4b0 74 68 65 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65  theld() .** inte
2a4c0 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73  rface should als
2a4d0 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20  o return 1 when 
2a4e0 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  given a NULL poi
2a4f0 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nter..*/.int sql
2a500 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
2a510 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
2a520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
2a530 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74  ex_notheld(sqlit
2a540 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
2a550 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
2a560 65 78 20 54 79 70 65 73 20 7b 46 31 37 30 30 31  ex Types {F17001
2a570 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 30 32 7d  }.**.** {F17002}
2a580 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   The [sqlite3_mu
2a590 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74  tex_alloc()] int
2a5a0 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73  erface takes a s
2a5b0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
2a5c0 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f  * which is one o
2a5d0 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
2a5e0 63 6f 6e 73 74 61 6e 74 73 2e 20 7b 45 4e 44 7d  constants. {END}
2a5f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2a600 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20  TE_MUTEX_FAST   
2a610 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
2a620 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
2a630 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
2a640 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2a650 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
2a660 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66  MASTER    2.#def
2a670 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
2a680 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20  _STATIC_MEM     
2a690 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    3  /* sqlite3_
2a6a0 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66  malloc() */.#def
2a6b0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
2a6c0 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20  _STATIC_MEM2    
2a6d0 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
2a6e0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2a6f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2a700 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
2a710 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20  PRNG      5  /* 
2a720 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29  sqlite3_random()
2a730 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2a740 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
2a750 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20  LRU       6  /* 
2a760 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f  lru page list */
2a770 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a780 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74  : Low-Level Cont
2a790 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 20  rol Of Database 
2a7a0 46 69 6c 65 73 20 7b 46 31 31 33 30 30 7d 0a 2a  Files {F11300}.*
2a7b0 2a 0a 2a 2a 20 7b 46 31 31 33 30 31 7d 20 54 68  *.** {F11301} Th
2a7c0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
2a7d0 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
2a7e0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72  face makes a dir
2a7f0 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ect call to the.
2a800 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
2a810 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b  method for the [
2a820 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
2a830 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  ds] object assoc
2a840 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  iated.** with a 
2a850 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
2a860 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  ase identified b
2a870 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
2a880 75 6d 65 6e 74 2e 20 7b 46 31 31 33 30 32 7d 20  ument. {F11302} 
2a890 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  The.** name of t
2a8a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 74  he database is t
2a8b0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2a8c0 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
2a8d0 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   by the.** <a hr
2a8e0 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e  ef="lang_attach.
2a8f0 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e  html">ATTACH</a>
2a900 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61   SQL command tha
2a910 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20  t opened the.** 
2a920 64 61 74 61 62 61 73 65 2e 20 7b 46 31 31 33 30  database. {F1130
2a930 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68  3} To control th
2a940 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
2a950 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61  file, use the na
2a960 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20  me "main".** or 
2a970 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
2a980 7b 46 31 31 33 30 34 7d 20 54 68 65 20 74 68 69  {F11304} The thi
2a990 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
2a9a0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2a9b0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20   routine.** are 
2a9c0 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 20  passed directly 
2a9d0 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73  through to the s
2a9e0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
2a9f0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a  parameters of.**
2aa00 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
2aa10 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 46 31 31 33  l method.  {F113
2aa20 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  05} The return v
2aa30 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c  alue of the xFil
2aa40 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68  eControl.** meth
2aa50 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72  od becomes the r
2aa60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2aa70 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a  his routine..**.
2aa80 2a 2a 20 7b 46 31 31 33 30 36 7d 20 49 66 20 74  ** {F11306} If t
2aa90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2aaa0 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f  ter (zDbName) do
2aab0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65  es not match the
2aac0 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20   name of any.** 
2aad0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69  open database fi
2aae0 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  le, then SQLITE_
2aaf0 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65  ERROR is returne
2ab00 64 2e 20 7b 46 31 31 33 30 37 7d 20 54 68 69 73  d. {F11307} This
2ab10 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
2ab20 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64  s not remembered
2ab30 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
2ab40 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71   recalled by [sq
2ab50 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
2ab60 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2ab70 65 72 72 6d 73 67 28 29 5d 2e 20 7b 55 31 31 33  errmsg()]. {U113
2ab80 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79 69  08} The underlyi
2ab90 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ng xFileControl 
2aba0 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20  method might.** 
2abb0 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49  also return SQLI
2abc0 54 45 5f 45 52 52 4f 52 2e 20 20 7b 55 31 31 33  TE_ERROR.  {U113
2abd0 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f 20  09} There is no 
2abe0 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69  way to distingui
2abf0 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e  sh between.** an
2ac00 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61   incorrect zDbNa
2ac10 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45  me and an SQLITE
2ac20 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72  _ERROR return fr
2ac30 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  om the underlyin
2ac40 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  g.** xFileContro
2ac50 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a  l method. {END}.
2ac60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2ac70 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
2ac80 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20  CKSTATE].*/.int 
2ac90 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
2aca0 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63  trol(sqlite3*, c
2acb0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
2acc0 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  me, int op, void
2acd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20  *);../*.** Undo 
2ace0 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f  the hack that co
2acf0 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20  nverts floating 
2ad00 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69  point types to i
2ad10 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75  nteger for.** bu
2ad20 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f  ilds on processo
2ad30 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74  rs without float
2ad40 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2ad50 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
2ad60 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
2ad70 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20  G_POINT.# undef 
2ad80 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23  double.#endif..#
2ad90 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75  ifdef __cplusplu
2ada0 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74  s.}  /* End of t
2adb0 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20  he 'extern "C"' 
2adc0 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a  block */.#endif.
2add0 23 65 6e 64 69 66 0a                             #endif.