Documentation Source Text

Hex Artifact Content
Login

Artifact b6f66e819a40e68b61f688731aee097a31b51286:


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 54 68  F10010}.**.** Th
0850: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0860: 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 53   and SQLITE_VERS
0870: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69  ION_NUMBER #defi
0880: 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71  nes in.** the sq
0890: 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70 65  lite3.h file spe
08a0: 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f 6e  cify the version
08b0: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68 20   of SQLite with 
08c0: 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 65  which.** that he
08d0: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73  ader file is ass
08e0: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  ociated..**.** T
08f0: 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 20  he "version" of 
0900: 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72 6f  SQLite is a stro
0910: 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ng of the form "
0920: 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70  X.Y.Z"..** The p
0930: 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f 72  hrase "alpha" or
0940: 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62 65   "beta" might be
0950: 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72 20   appended after 
0960: 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20  the Z..** The X 
0970: 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 76  value is major v
0980: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c  ersion number al
0990: 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65  ways 3 in SQLite
09a0: 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  3..** The X valu
09b0: 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  e only changes w
09c0: 68 65 6e 20 20 62 61 63 6b 77 61 72 64 73 20 63  hen  backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61   break.** backwa
0a10: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0a20: 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65 20  y.  The Y value 
0a30: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0a40: 73 69 6f 6e 0a 2a 2a 20 6e 75 6d 62 65 72 20 61  sion.** number a
0a50: 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  nd only changes 
0a60: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72  when.** there ar
0a70: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20  e major feature 
0a80: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61  enhancements tha
0a90: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63  t are forwards c
0aa0: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74  ompatible.** but
0ab0: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63   not backwards c
0ac0: 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20  ompatible.  The 
0ad0: 5a 20 76 61 6c 75 65 20 69 73 20 72 65 6c 65 61  Z value is relea
0ae0: 73 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 61 6e 64  se number.** and
0af0: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0b00: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0b10: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0b20: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 20 59  back to 0 when Y
0b30: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e   is incremented.
0b40: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
0b50: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
0b60: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
0b70: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
0b80: 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a  number()]..**.**
0b90: 20 43 4f 56 45 4e 41 4e 54 53 3a 0a 2a 2a 0a 2a   COVENANTS:.**.*
0ba0: 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20 53  * {F10011} The S
0bb0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23 64  QLITE_VERSION #d
0bc0: 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71 6c  efine in the sql
0bd0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69  ite3.h header fi
0be0: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  le.**          e
0bf0: 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74  valuates to a st
0c00: 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61  ring literal tha
0c10: 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20  t is the SQLite 
0c20: 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  version.**      
0c30: 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20 74      with which t
0c40: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 69  he header file i
0c50: 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a  s associated..**
0c60: 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68 65  .** {F10014} The
0c70: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0c80: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 72  NUMBER #define r
0c90: 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e  esolves to an in
0ca0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
0cb0: 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65    with the value
0cc0: 20 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59    (X*1000000 + Y
0cd0: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0ce0: 20 58 2c 20 59 2c 20 61 6e 64 0a 2a 2a 20 20 20   X, Y, and.**   
0cf0: 20 20 20 20 20 20 20 5a 20 61 72 65 20 74 68 65         Z are the
0d00: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0d10: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0d20: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0d30: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
0d40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
0d50: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
0d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0d70: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
0d80: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
0d90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0da0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
0db0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0dc0: 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a 0a 2a  rs {F10020}.**.*
0dd0: 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73  * These features
0de0: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
0df0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
0e00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
0e10: 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51  SION].** and [SQ
0e20: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0e30: 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e  BER] #defines in
0e40: 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74   the header, but
0e50: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a   are associated.
0e60: 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ** with the libr
0e70: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ary instead of t
0e80: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20  he header file. 
0e90: 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61   Cautious progra
0ea0: 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69  mmers might.** i
0eb0: 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69  nclude a check i
0ec0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
0ed0: 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68  ion to verify th
0ee0: 61 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  at .** sqlite3_l
0ef0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
0f00: 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  () always return
0f10: 73 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20  s the value .** 
0f20: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
0f30: 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NUMBER]..**.** T
0f40: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
0f50: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
0f60: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d   returns the sam
0f70: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
0f80: 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71   is.** in the sq
0f90: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
0fa0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e  string constant.
0fb0: 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69    The function i
0fc0: 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  s provided.** fo
0fd0: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
0fe0: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
0ff0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
1000: 65 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  e direct access 
1010: 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e  to string.** con
1020: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
1030: 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 43 4f 56  e DLL..**.** COV
1040: 45 4e 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  ENANTS:.**.** {F
1050: 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  10021} The [sqli
1060: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1070: 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61  umber()] interfa
1080: 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ce returns an in
1090: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
10a0: 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49    equal to [SQLI
10b0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
10c0: 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30  R]. .**.** {F100
10d0: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
10e0: 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67  _version] string
10f0: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
1100: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  ns the text of t
1110: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1120: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
1130: 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b  string. .**.** {
1140: 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c  F10023} The [sql
1150: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1160: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
1170: 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
1180: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1190: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11a0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11b0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
11c0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
11d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
11e0: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
11f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1200: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1210: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1220: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1230: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1240: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1250: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1260: 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d  eadsafe {F10100}
1270: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1280: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1290: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
12a0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
12b0: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  the SQLITE_THREA
12c0: 44 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 65  DSAFE C preproce
12d0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72  ssor macro is tr
12e0: 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  ue, mutexes.** a
12f0: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1300: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1310: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20  afe.  When that 
1320: 6d 61 63 72 6f 20 6f 73 20 66 61 6c 73 65 2c 0a  macro os false,.
1330: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1340: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1350: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1360: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1370: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1380: 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  e from more than
1390: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
13a0: 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d 65  ** There is a me
13b0: 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d  asurable perform
13c0: 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f 72  ance penalty for
13d0: 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   enabling mutexe
13e0: 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65  s..** So if spee
13f0: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69  d is of utmost i
1400: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61  mportance, it ma
1410: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73  kes sense to dis
1420: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  able.** the mute
1430: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61  xes.  But for ma
1440: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75  ximum safety, mu
1450: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20  texes should be 
1460: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20  enabled..** The 
1470: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
1480: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
1490: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
14a0: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
14b0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
14c0: 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20  by a program to 
14d0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
14e0: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
14f0: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1500: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1510: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1520: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1530: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1540: 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  he SQLITE_THREAD
1550: 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  SAFE macro..**.*
1560: 2a 20 43 4f 56 45 4e 41 4e 54 53 3a 0a 2a 2a 0a  * COVENANTS:.**.
1570: 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65 20  ** {F10101} The 
1580: 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1590: 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  afe()] function 
15a0: 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 6f 20  returns nonzero 
15b0: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
15c0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
15d0: 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 74 65  ed with its mute
15e0: 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 7a  xes enabled or z
15f0: 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ero.**          
1600: 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  if SQLite was co
1610: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1620: 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f  xes disabled..*/
1630: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
1640: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
1650: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1660: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1670: 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32 30  ion Handle {F120
1680: 30 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  00}.**.** Each o
1690: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
16a0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
16b0: 65 64 20 62 79 20 70 6f 69 6e 74 65 72 20 74 6f  ed by pointer to
16c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
16d0: 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65 20 73 74  the.** opaque st
16e0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
16f0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
1700: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
1710: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
1720: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
1730: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
1740: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1750: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1760: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1770: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1780: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
1790: 63 6f 6e 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20  constructors.** 
17a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
17b0: 73 65 28 29 5d 20 69 73 20 69 74 73 20 64 65 73  se()] is its des
17c0: 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20  tructor.  There 
17d0: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69  are many other i
17e0: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 28 73 75  nterfaces.** (su
17f0: 63 68 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 70  ch as [sqlite3_p
1800: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
1810: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1820: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a  nction()], and.*
1830: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1840: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61  timeout()] to na
1850: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68  me but three) th
1860: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f  at are methods o
1870: 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  n this.** object
1880: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1890: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
18a0: 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  te3;.../*.** CAP
18b0: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
18c0: 74 65 67 65 72 20 54 79 70 65 73 20 7b 46 31 30  teger Types {F10
18d0: 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  200}.**.** Becau
18e0: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
18f0: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1900: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1910: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1920: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1930: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1940: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1950: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1960: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1970: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1980: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1990: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
19a0: 72 65 64 20 74 79 70 65 0a 2a 2a 20 64 65 66 69  red type.** defi
19b0: 6e 69 74 69 6f 6e 73 2e 20 20 54 68 65 20 73 71  nitions.  The sq
19c0: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
19d0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
19e0: 65 73 20 61 72 65 0a 2a 2a 20 73 75 70 70 6f 72  es are.** suppor
19f0: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
1a00: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
1a10: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 43 4f 56 45  only..**.** COVE
1a20: 4e 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  NANTS:.**.** {F1
1a30: 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0201} The [sqlit
1a40: 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71  e_int64] and [sq
1a50: 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70  lite3_int64] typ
1a60: 65 73 20 73 70 65 63 69 66 79 20 61 0a 2a 2a 20  es specify a.** 
1a70: 20 20 20 20 20 20 20 20 20 36 34 2d 62 69 74 20           64-bit 
1a80: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
1a90: 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54  **.** {F10202} T
1aa0: 68 65 20 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36  he [sqlite_uint6
1ab0: 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  4] and [sqlite3_
1ac0: 75 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73 70  uint64] types sp
1ad0: 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20  ecify.**        
1ae0: 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67    a 64-bit unsig
1af0: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a  ned integer..*/.
1b00: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
1b10: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
1b20: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1b30: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
1b40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
1b50: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
1b60: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
1b70: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
1b80: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
1b90: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
1ba0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
1bb0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
1bc0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
1bd0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
1be0: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1bf0: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
1c00: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
1c10: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
1c20: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
1c30: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
1c40: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1c50: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
1c60: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1c70: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
1c80: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
1c90: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
1ca0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
1cb0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
1cc0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
1cd0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
1ce0: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
1cf0: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
1d00: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a  floating-point.*
1d10: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1d20: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
1d30: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
1d40: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
1d50: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
1d60: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
1d70: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
1d80: 6e 65 63 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d  nection {F12010}
1d90: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1da0: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1db0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1dc0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 20  qlite3] object. 
1dd0: 20 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74   .**.** Applicat
1de0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c  ions should [sql
1df0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
1e00: 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a  finalize] all.**
1e10: 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
1e20: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1e30: 65 6e 74 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ents] and.** [sq
1e40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
1e50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73   | close] all [s
1e60: 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c  qlite3_blob | BL
1e70: 4f 42 73 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61  OBs] .** associa
1e80: 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71  ted with the [sq
1e90: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
1ea0: 69 6f 72 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70  ior.** to attemp
1eb0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
1ec0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1ed0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e  ct..**.** <todo>
1ee0: 57 68 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20  What happens to 
1ef0: 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74  pending transact
1f00: 69 6f 6e 73 3f 20 20 41 72 65 20 74 68 65 79 0a  ions?  Are they.
1f10: 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20  ** rolled back, 
1f20: 6f 72 20 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74  or abandoned?</t
1f30: 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 43 4f 56 45 4e  odo>.**.** COVEN
1f40: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
1f50: 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  011} The [sqlite
1f60: 33 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72  3_close()] inter
1f70: 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e  face destroys an
1f80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1f90: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  t.**          al
1fa0: 6c 6f 63 61 74 65 64 20 62 79 20 61 20 70 72 69  located by a pri
1fb0: 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
1fc0: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20  te3_open()],.** 
1fd0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1fe0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20  3_open16()], or 
1ff0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2000: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  ()]..**.** {F120
2010: 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2020: 5f 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69  _close()] functi
2030: 6f 6e 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20  on releases all 
2040: 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74  memory used by t
2050: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2060: 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c  onnection and cl
2070: 6f 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69  oses all open fi
2080: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  les..**.** {F120
2090: 31 33 7d 20 49 66 20 74 68 65 20 64 61 74 61 62  13} If the datab
20a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
20b0: 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
20c0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d      [sqlite3_stm
20d0: 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
20e0: 74 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61  tements] that ha
20f0: 76 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20  ve not been.**  
2100: 20 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65          finalize
2110: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2120: 6e 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20  nalize()], then 
2130: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2140: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2150: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
2160: 53 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74  SY] and leaves t
2170: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  he connection op
2180: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  en..**.** {F1201
2190: 34 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65  4} Giving sqlite
21a0: 33 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c  3_close() a NULL
21b0: 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
21c0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
21d0: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
21e0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20  .**.** {U12015} 
21f0: 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  The parameter to
2200: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2210: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73  )] must be an [s
2220: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a  qlite3] object.*
2230: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2240: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  er previously ob
2250: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2260: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
2270: 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
2280: 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
2290: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  NULL..**.** {U12
22a0: 30 31 35 7d 20 54 68 65 20 70 61 72 61 6d 65 74  015} The paramet
22b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
22c0: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74  lose()] must not
22d0: 20 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69   have been previ
22e0: 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
22f0: 20 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74    closed..*/.int
2300: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
2310: 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a  qlite3 *);../*.*
2320: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
2330: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2340: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
2350: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
2360: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
2370: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
2380: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
2390: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
23a0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
23b0: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
23c0: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
23d0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
23e0: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
23f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
2400: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
2410: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b  tion Interface {
2420: 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12100}.**.** Th
2430: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2440: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
2450: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
2460: 66 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65  f running.** one
2470: 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61   or more SQL sta
2480: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
2490: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
24a0: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61    The.** SQL sta
24b0: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
24c0: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
24d0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
24e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
24f0: 28 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  ().  The stateme
2500: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2510: 64 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20  d one by one.** 
2520: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2530: 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
2540: 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74  rrupt is encount
2550: 65 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c  ered or.** until
2560: 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f   they are all do
2570: 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72  ne.  The 3rd par
2580: 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74  ameter is an opt
2590: 69 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63  ional.** callbac
25a0: 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  k that is invoke
25b0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
25c0: 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79  row of any query
25d0: 20 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64   results.** prod
25e0: 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20  uced by the SQL 
25f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65  statements.  The
2600: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
2610: 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f  ells where.** to
2620: 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72   write any error
2630: 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a   messages..**.**
2640: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
2650: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
2660: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
2670: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c  terms of.** [sql
2680: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2690: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
26a0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
26b0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
26c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
26d0: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  xec() routine do
26e0: 65 73 20 6e 6f 74 68 69 6e 67 20 74 68 61 74 20  es nothing that 
26f0: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a  cannot be done.*
2700: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
2710: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2720: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2730: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2740: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
2750: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2760: 73 20 6a 75 73 74 20 61 20 63 6f 6e 76 65 6e 69  s just a conveni
2770: 65 6e 74 20 77 72 61 70 70 65 72 2e 0a 2a 2a 0a  ent wrapper..**.
2780: 2a 2a 20 43 4f 56 45 4e 41 4e 54 53 3a 0a 2a 2a  ** COVENANTS:.**
2790: 20 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 54 68   .** {F12101} Th
27a0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
27b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 65 76 61  )] interface eva
27c0: 6c 75 61 74 65 73 20 7a 65 72 6f 20 6f 72 20 6d  luates zero or m
27d0: 6f 72 65 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20  ore UTF-8.**    
27e0: 20 20 20 20 20 20 65 6e 63 6f 64 65 64 2c 20 73        encoded, s
27f0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
2800: 65 64 2c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ed, SQL statemen
2810: 74 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ts in the.**    
2820: 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
2830: 6e 61 74 65 64 20 73 74 72 69 6e 67 20 6f 66 20  nated string of 
2840: 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
2850: 72 20 77 69 74 68 69 6e 20 74 68 65 0a 2a 2a 20  r within the.** 
2860: 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2870: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2880: 5d 20 6f 62 6a 65 63 74 20 67 69 76 65 6e 20 69  ] object given i
2890: 6e 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  n the 1st parame
28a0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ter..**.** {F121
28b0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  04} The return v
28c0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
28d0: 5f 65 78 65 63 28 29 5d 20 69 73 20 53 51 4c 49  _exec()] is SQLI
28e0: 54 45 5f 4f 4b 20 69 66 20 61 6c 6c 0a 2a 2a 20  TE_OK if all.** 
28f0: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
2900: 74 65 6d 65 6e 74 20 72 75 6e 20 73 75 63 63 65  tement run succe
2910: 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ssfully..**.** {
2920: 46 31 32 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f  F12107} If one o
2930: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51  r more of the SQ
2940: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e  L statements han
2950: 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ded to [sqlite3_
2960: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
2970: 20 20 20 20 72 65 74 75 72 6e 20 72 65 73 75 6c      return resul
2980: 74 73 20 61 6e 64 20 74 68 65 20 33 72 64 20 70  ts and the 3rd p
2990: 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20  arameter is not 
29a0: 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  NULL, then.**   
29b0: 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62         the callb
29c0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65  ack function spe
29d0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 33 72  cified by the 3r
29e0: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  d parameter is.*
29f0: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b  *          invok
2a00: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2a10: 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a   row of result..
2a20: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 30 7d 20 49  **.** {F12110} I
2a30: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
2a40: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
2a50: 6f 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71  o value then [sq
2a60: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
2a70: 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 61            will a
2a80: 62 6f 72 74 65 64 20 74 68 65 20 53 51 4c 20 73  borted the SQL s
2a90: 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63  tatement it is c
2aa0: 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74  urrently evaluat
2ab0: 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ing,.**         
2ac0: 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71   skip all subseq
2ad0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
2ae0: 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  nts, and return 
2af0: 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
2b00: 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
2b10: 6f 3e 57 68 61 74 20 68 61 70 70 65 6e 73 20 74  o>What happens t
2b20: 6f 20 2a 65 72 72 6d 73 67 20 68 65 72 65 3f 20  o *errmsg here? 
2b30: 20 44 6f 65 73 20 74 68 65 20 72 65 73 75 6c 74   Does the result
2b40: 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 20 20 20   code for.**    
2b50: 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 65 72        sqlite3_er
2b60: 72 63 6f 64 65 28 29 20 67 65 74 20 73 65 74 3f  rcode() get set?
2b70: 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
2b80: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69  12113} The [sqli
2b90: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
2ba0: 69 6e 65 20 77 69 6c 6c 20 70 61 73 73 20 69 74  ine will pass it
2bb0: 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 4th parameter 
2bc0: 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20  through.**      
2bd0: 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20 70      as the 1st p
2be0: 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2bf0: 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2c00: 7b 46 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71  {F12116} The [sq
2c10: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
2c20: 75 74 69 6e 65 20 73 65 74 73 20 74 68 65 20 32  utine sets the 2
2c30: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2c40: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
2c50: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74  callback to be t
2c60: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2c70: 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72  umns in the curr
2c80: 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20  ent row of.**   
2c90: 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a         result..*
2ca0: 2a 0a 2a 2a 20 7b 46 31 32 31 31 39 7d 20 54 68  *.** {F12119} Th
2cb0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
2cc0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  )] routine sets 
2cd0: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2ce0: 72 20 6f 66 20 69 74 73 20 0a 2a 2a 20 20 20 20  r of its .**    
2cf0: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
2d00: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66  o be an array of
2d10: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
2d20: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
2d30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
2d40: 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  ues for each col
2d50: 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2d60: 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f  nt result set ro
2d70: 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  w as.**         
2d80: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2d90: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2da0: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ext()]..**.** {F
2db0: 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69  12122} The [sqli
2dc0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
2dd0: 69 6e 65 20 73 65 74 73 20 74 68 65 20 34 74 68  ine sets the 4th
2de0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74   parameter of it
2df0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  s.**          ca
2e00: 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20  llback to be an 
2e10: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
2e20: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c  s to strings hol
2e30: 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ding the.**     
2e40: 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65       names of re
2e50: 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20  sult columns as 
2e60: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2e70: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2e80: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  me()]..**.** {F1
2e90: 32 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64  2125} If the 3rd
2ea0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2eb0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
2ec0: 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20  s NULL then.**  
2ed0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2ee0: 5f 65 78 65 63 28 29 5d 20 6e 65 76 65 72 20 69  _exec()] never i
2ef0: 6e 76 6f 6b 65 73 20 61 20 63 61 6c 6c 62 61 63  nvokes a callbac
2f00: 6b 2e 20 20 41 6c 6c 20 71 75 65 72 79 0a 2a 2a  k.  All query.**
2f10: 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
2f20: 73 20 61 72 65 20 73 69 6c 65 6e 74 6c 79 20 64  s are silently d
2f30: 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  iscarded..**.** 
2f40: 7b 46 31 32 31 32 38 7d 20 49 66 20 61 6e 20 65  {F12128} If an e
2f50: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
2f60: 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61  e parsing or eva
2f70: 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74  luating any of t
2f80: 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20  he SQL.**       
2f90: 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61     statements ha
2fa0: 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  nded to [sqlite3
2fb0: 5f 65 78 65 63 28 29 5d 20 74 68 65 6e 20 5b 73  _exec()] then [s
2fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 77  qlite3_exec()] w
2fd0: 69 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ill.**          
2fe0: 72 65 74 75 72 6e 20 61 6e 20 5b 53 51 4c 49 54  return an [SQLIT
2ff0: 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
3000: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
3010: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
3020: 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20  .** {F12131} If 
3030: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3040: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3050: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3060: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3070: 20 20 20 20 20 20 20 68 61 6e 64 65 64 20 74 6f         handed to
3080: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3090: 5d 20 61 6e 64 20 69 66 20 74 68 65 20 35 74 68  ] and if the 5th
30a0: 20 70 61 72 61 6d 65 74 65 72 20 28 65 72 72 6d   parameter (errm
30b0: 73 67 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sg).**          
30c0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
30d0: 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ()] is not NULL,
30e0: 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6d   then an error m
30f0: 65 73 73 61 67 65 20 69 73 0a 2a 2a 20 20 20 20  essage is.**    
3100: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20        allocated 
3110: 75 73 69 6e 67 20 74 68 65 20 65 71 75 69 76 61  using the equiva
3120: 6c 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33  lent of [sqlite3
3130: 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 0a  _mprintf()] and.
3140: 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 65 72 72  **          *err
3150: 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70  msg is made to p
3160: 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d 65 73  oint to that mes
3170: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  sage..**.** {F12
3180: 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  134} The [sqlite
3190: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
31a0: 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
31b0: 65 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  e the value of.*
31c0: 2a 20 20 20 20 20 20 20 20 20 20 2a 65 72 72 6d  *          *errm
31d0: 73 67 20 69 66 20 65 72 72 6d 73 67 20 69 73 20  sg if errmsg is 
31e0: 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 72 65  NULL or if there
31f0: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a   are no errors..
3200: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54  **.** {F12137} T
3210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3220: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  ()] function set
3230: 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
3240: 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
3250: 20 20 20 20 20 20 20 20 20 61 63 63 65 73 73 69           accessi
3260: 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
3270: 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
3280: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
3290: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  )]..**.** LIMITA
32a0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
32b0: 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74 20  2141} The first 
32c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
32d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75  lite3_exec()] mu
32e0: 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61  st be an valid a
32f0: 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 20  nd open.**      
3300: 20 20 20 20 5b 73 71 6c 69 74 65 33 20 7c 20 64      [sqlite3 | d
3310: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3320: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31  on]..**.** {U121
3330: 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65  42} The database
3340: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
3350: 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77   not be closed w
3360: 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  hile.**         
3370: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3380: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ] is running..**
3390: 20 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20 54 68   .** {U12143} Th
33a0: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
33b0: 6f 6e 20 69 73 20 73 68 6f 75 6c 64 20 75 73 65  on is should use
33c0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
33d0: 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20  ] to free.**    
33e0: 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79        the memory
33f0: 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73   that *errmsg is
3400: 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61   left pointing a
3410: 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72  t once the error
3420: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73  .**          mes
3430: 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  sage is no longe
3440: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  r needed..**.** 
3450: 7b 55 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c  {U12145} The SQL
3460: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
3470: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
3480: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3490: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20  _exec()].**     
34a0: 20 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e       must remain
34b0: 20 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65   unchanged while
34c0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
34d0: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  ] is running..*/
34e0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65  .int sqlite3_exe
34f0: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
3500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3510: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3520: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
3530: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
3540: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
3550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3560: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
3570: 20 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69   evaluted */.  i
3580: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3590: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
35a0: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
35b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
35c0: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
35d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
35f0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3600: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3610: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3630: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3640: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3650: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3660: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3670: 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 31 30  lt Codes {F10210
3680: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  }.** KEYWORDS: S
3690: 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d  QLITE_OK.**.** M
36a0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
36b0: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
36c0: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
36d0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
36e0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
36f0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3700: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3710: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  ailure..**.** Se
3720: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
3730: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
3740: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3750: 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  es].*/.#define S
3760: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
3770: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
3780: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
3790: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
37a0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
37b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
37c0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
37d0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
37e0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
37f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3800: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
3810: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
3820: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
3830: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
3840: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
3850: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
3860: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
3870: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3880: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
3890: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
38a0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
38b0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
38c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
38d0: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
38e0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
38f0: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
3900: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3910: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
3920: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
3930: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
3940: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
3950: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
3960: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
3970: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
3980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3990: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
39a0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
39b0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
39c0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
39d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
39e0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
39f0: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
3a00: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
3a10: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
3a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3a30: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
3a40: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
3a50: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
3a60: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
3a70: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
3a80: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
3a90: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
3aa0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
3ab0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3ac0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
3ad0: 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  2   /* NOT USED.
3ae0: 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64   Table or record
3af0: 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64   not found */.#d
3b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
3b10: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
3b20: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
3b30: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
3b40: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
3b50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
3b60: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
3b70: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
3b80: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
3b90: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3ba0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
3bb0: 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  15   /* NOT USED
3bc0: 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  . Database lock 
3bd0: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
3be0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3bf0: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
3c00: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
3c10: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
3c20: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
3c30: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
3c40: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
3c50: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
3c60: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
3c70: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
3c80: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
3c90: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
3ca0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3cb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
3cc0: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
3cd0: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
3ce0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
3cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
3d00: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
3d10: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
3d20: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
3d30: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
3d40: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
3d50: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
3d60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3d70: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
3d80: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
3d90: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
3da0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
3db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3dc0: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
3dd0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
3de0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
3df0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
3e00: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
3e10: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
3e20: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
3e30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e40: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
3e50: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
3e60: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
3e70: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
3e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3e90: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
3ea0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
3eb0: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
3ec0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
3ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3ee0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
3ef0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
3f00: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
3f10: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
3f20: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
3f30: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
3f40: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
3f50: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
3f60: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
3f70: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
3f80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3f90: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
3fa0: 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32 30 7d  t Codes {F10220}
3fb0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
3fc0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
3fd0: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
3fe0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
3ff0: 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65  one of 26 intege
4000: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  r.** [SQLITE_OK 
4010: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e  | result codes].
4020: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4030: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4040: 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66 20  that.** many of 
4050: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4060: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72 73  es are too cours
4070: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4080: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4090: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
40a0: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
40b0: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
40c0: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
40d0: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
40e0: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
40f0: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4100: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4110: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4120: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4130: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4140: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4150: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4160: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4170: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4180: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4190: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
41a0: 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c   codes are enabl
41b0: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
41c0: 2a 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  * for each datab
41d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
41e0: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
41f0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4200: 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50  t_codes()].** AP
4210: 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f  I..** .** Some o
4220: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
4230: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4240: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
4250: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
4260: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
4270: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
4280: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
4290: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
42a0: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
42b0: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
42c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
42d0: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
42e0: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
42f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
4300: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
4310: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4320: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
4330: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
4340: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
4350: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
4360: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
4370: 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 43 4f   zero..** .** CO
4380: 56 45 4e 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  VENANTS:.**.** {
4390: 46 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62  F10223} The symb
43a0: 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e  olic name for an
43b0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
43c0: 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63 6f 6e   code always con
43d0: 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
43e0: 20 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d    a related prim
43f0: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
4400: 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a  as a prefix..**.
4410: 2a 2a 20 7b 46 31 30 32 32 34 7d 20 50 72 69 6d  ** {F10224} Prim
4420: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
4430: 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 61 20  names contain a 
4440: 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61  single "_" chara
4450: 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  cter..**.** {F10
4460: 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65  225} Extended re
4470: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20  sult code names 
4480: 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d  contain two or m
4490: 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  ore "_" characte
44a0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32  rs..**.** {F1022
44b0: 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76  6} The numeric v
44c0: 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e  alue of an exten
44d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
44e0: 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
44f0: 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69 63           numeric
4500: 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63 6f   value of its co
4510: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d  rresponding prim
4520: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
4530: 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  it.**          i
4540: 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ts least signifi
4550: 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a  cant 8 bits..*/.
4560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4570: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
4580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4590: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
45a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
45b0: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28 53  SHORT_READ    (S
45c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
45d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
45e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
45f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4600: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4620: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
4630: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4640: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4660: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 28  _DIR_FSYNC     (
4670: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4680: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4690: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
46a0: 43 41 54 45 20 20 20 20 20 20 28 53 51 4c 49 54  CATE      (SQLIT
46b0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
46c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
46d0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
46e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
46f0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
4700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4710: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
4720: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4730: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
4740: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
4750: 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  OCK        (SQLI
4760: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
4770: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4780: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
4790: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
47a0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
47b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
47c0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
47d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
47e0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
47f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4800: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 28 53  NOMEM         (S
4810: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4820: 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  2<<8))../*.** CA
4830: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
4840: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
4850: 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30 7d 0a  ations {F10230}.
4860: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
4870: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
4880: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
4890: 68 65 6e 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  hen.** 3rd param
48a0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
48b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
48c0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
48d0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
48e0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70  meter to the xOp
48f0: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
4900: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
4910: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4930: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
4940: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4960: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
4970: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
4980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4990: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
49a0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
49c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
49d0: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
49e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
49f0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
4a00: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
4a10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4a20: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
4a30: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4a50: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
4a60: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4a80: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
4a90: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
4aa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4ab0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
4ac0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4ae0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
4af0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
4b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4b10: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
4b20: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
4b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4b40: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
4b50: 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a    0x00004000../*
4b60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
4b70: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
4b80: 74 69 63 73 20 7b 46 31 30 32 34 30 7d 0a 2a 2a  tics {F10240}.**
4b90: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
4ba0: 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68  apabilities meth
4bb0: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
4bc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
4bd0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
4be0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
4bf0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
4c00: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69   the these.** bi
4c10: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
4c20: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
4c30: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
4c40: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
4c50: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
4c60: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
4c70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
4c80: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
4c90: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
4ca0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4cb0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
4cc0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
4cd0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
4ce0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
4cf0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4d00: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
4d10: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
4d20: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
4d30: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
4d40: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
4d50: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
4d60: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
4d70: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
4d80: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
4d90: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
4da0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4db0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
4dc0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
4dd0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
4de0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
4df0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
4e00: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
4e10: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
4e20: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
4e30: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
4e40: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
4e50: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
4e60: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
4e70: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
4e80: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
4e90: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
4ea0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
4eb0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
4ec0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
4ed0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
4ee0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4ef0: 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  C          0x000
4f00: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
4f10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4f20: 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30  C512       0x000
4f30: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
4f40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4f50: 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C1K        0x000
4f60: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
4f70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4f80: 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C2K        0x000
4f90: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
4fa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4fb0: 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C4K        0x000
4fc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
4fd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4fe0: 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C8K        0x000
4ff0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
5000: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5010: 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30  C16K       0x000
5020: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
5030: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5040: 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30  C32K       0x000
5050: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
5060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5070: 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30  C64K       0x000
5080: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5090: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
50a0: 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30  APPEND     0x000
50b0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
50c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
50d0: 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30  NTIAL      0x000
50e0: 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00400../*.** CAP
50f0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
5100: 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 30 32  ing Levels {F102
5110: 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  50}.**.** SQLite
5120: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
5130: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
5140: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
5150: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
5160: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
5170: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
5180: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
5190: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
51a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
51b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
51c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
51d0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
51e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
51f0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
5200: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
5210: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5220: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
5230: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
5240: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
5250: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5260: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
5270: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5280: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
5290: 20 54 79 70 65 20 46 6c 61 67 73 20 7b 46 31 30   Type Flags {F10
52a0: 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  260}.**.** When 
52b0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
52c0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
52d0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
52e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
52f0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
5300: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
5310: 74 68 65 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74  the.** these int
5320: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
5330: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
5340: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
5350: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
5360: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
5370: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
5380: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
5390: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
53a0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
53b0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
53c0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
53d0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
53e0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54  ot be flushed. T
53f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
5400: 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a 20  ORMAL means .** 
5410: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
5420: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
5430: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
5440: 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73  _FULL flag means
5450: 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20   .** to use Mac 
5460: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
5470: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
5480: 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  sync()..*/.#defi
5490: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
54a0: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
54b0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
54c0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
54d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
54f0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
5500: 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a   0x00010.../*.**
5510: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
5520: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
5530: 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31 31 30  e Handle {F11110
5540: 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  }.**.** An [sqli
5550: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
5560: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
5570: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
5580: 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  OS.** interface 
5590: 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75  layer.  Individu
55a0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  al OS interface 
55b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
55c0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
55d0: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
55e0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
55f0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
5600: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
5610: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
5620: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
5630: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
5640: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5650: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5660: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
5670: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
5680: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
5690: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
56a0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
56b0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
56c0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
56d0: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
56e0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
56f0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
5700: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
5710: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
5720: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
5730: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
5740: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
5750: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
5760: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
5770: 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a 2a 2a  ject {F11120}.**
5780: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
5790: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
57a0: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
57b0: 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73   method contains
57c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
57d0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
57e0: 74 68 65 20 74 68 69 73 20 6f 62 6a 65 63 74 2e  the this object.
57f0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65    This object de
5800: 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74  fines the.** met
5810: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
5820: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
5830: 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20  rations against 
5840: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5850: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
5860: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
5870: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
5880: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5890: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
58a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
58b0: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
58c0: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
58d0: 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65  ync()..*  The se
58e0: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
58f0: 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20  n.** OS-X style 
5900: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53  fullsync.  The S
5910: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20  QLITE_SYNC_DATA 
5920: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
5930: 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61   in to.** indica
5940: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
5950: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
5960: 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  e and not its in
5970: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a  ode needs to be.
5980: 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a  ** synced..** .*
5990: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
59a0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
59b0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
59c0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
59d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
59e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
59f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5a00: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
5a10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5a20: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
5a30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5a40: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
5a50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5a60: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
5a70: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
5a80: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
5a90: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
5aa0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
5ab0: 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68  ck.  .** The xCh
5ac0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
5ad0: 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a  ) method looks.*
5ae0: 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20  * to see if any 
5af0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5b00: 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74  ion, either in t
5b10: 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f  his.** process o
5b20: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
5b30: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
5b40: 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c  ing an RESERVED,
5b50: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
5b60: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
5b70: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
5b80: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
5b90: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
5ba0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
5bb0: 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54  if not..** .** T
5bc0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
5bd0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
5be0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
5bf0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
5c00: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
5c10: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
5c20: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
5c30: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
5c40: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5c50: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
5c60: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
5c70: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
5c80: 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69  ument.** is an i
5c90: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
5ca0: 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   The third.** ar
5cb0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
5cc0: 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63  ric pointer whic
5cd0: 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  h is intended to
5ce0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   be a pointer.**
5cf0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
5d00: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
5d10: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
5d20: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
5d30: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
5d40: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
5d50: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
5d60: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
5d70: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
5d80: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
5d90: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
5da0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
5db0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
5dc0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
5dd0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
5de0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
5df0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
5e00: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
5e10: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
5e20: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
5e30: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
5e40: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
5e50: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
5e60: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
5e70: 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51  n use. .** A [SQ
5e80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
5e90: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
5ea0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
5eb0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
5ec0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
5ed0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
5ee0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
5ef0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
5f00: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20  uld use opcodes 
5f10: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
5f20: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
5f30: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
5f40: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
5f50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
5f60: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
5f70: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
5f80: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
5f90: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
5fa0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
5fb0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
5fc0: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
5fd0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
5fe0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
5ff0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6000: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6010: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6020: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6030: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6040: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6050: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6060: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6070: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6080: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6090: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
60a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
60b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
60c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
60d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
60e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
60f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
6100: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6110: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
6120: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6130: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
6140: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6150: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6160: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6170: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6180: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6190: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
61a0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
61b0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
61c0: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
61d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
61e0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
61f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
6200: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6210: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6220: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6230: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6240: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6260: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6270: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6280: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6290: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
62a0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
62b0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
62c0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
62d0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
62e0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
62f0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6300: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6310: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6320: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6330: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6340: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6350: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6360: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6370: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6380: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6390: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
63a0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
63b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
63c0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
63d0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
63e0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
63f0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6400: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6410: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6420: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
6430: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6440: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6450: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
6460: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
6470: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6480: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
6490: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
64a0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
64b0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
64c0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
64d0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
64e0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
64f0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
6500: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
6510: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
6520: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
6530: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6540: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
6550: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
6560: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6570: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
6580: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
6590: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
65a0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
65b0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
65c0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
65d0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
65e0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
65f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6600: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
6610: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6620: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6630: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
6640: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6650: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  e*);.  int (*xFi
6660: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
6670: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
6680: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
6690: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
66a0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
66b0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
66c0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
66d0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
66e0: 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f  *);.  /* Additio
66f0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
6700: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
6710: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
6720: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
6730: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
6740: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
6750: 20 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F11310}.**.** 
6760: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
6770: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
6780: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
6790: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
67a0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
67b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
67c0: 62 6a 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65  bject and to the
67d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
67e0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
67f0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
6800: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
6810: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
6820: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
6830: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
6840: 2a 20 6f 70 63 6f 64 65 20 63 61 73 65 73 20 74  * opcode cases t
6850: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
6860: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
6870: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
6880: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
6890: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
68a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
68b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
68c0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
68d0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
68e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
68f0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
6900: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
6910: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
6920: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
6930: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
6940: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
6950: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
6960: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
6970: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
6980: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
6990: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
69a0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
69b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
69c0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
69d0: 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a          1../*.**
69e0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
69f0: 20 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d   Handle {F17110}
6a00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
6a10: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
6a20: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
6a30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
6a40: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
6a50: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
6a60: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
6a70: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
6a80: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
6a90: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
6aa0: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
6ab0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
6ac0: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
6ad0: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
6ae0: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
6af0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
6b00: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
6b10: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
6b20: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
6b30: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
6b40: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6b50: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
6b60: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
6b70: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6b80: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46  erface Object {F
6b90: 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  11140}.**.** An 
6ba0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
6bb0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6bc0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
6bd0: 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  tween the.** SQL
6be0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
6bf0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
6c00: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
6c10: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
6c20: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
6c30: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
6c40: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
6c50: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystem"..**.** Th
6c60: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
6c70: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
6c80: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
6c90: 72 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20  r for future.** 
6ca0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
6cb0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
6cc0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
6cd0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
6ce0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
6cf0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
6d00: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a   is increased..*
6d10: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
6d20: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
6d30: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
6d40: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
6d50: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
6d60: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
6d70: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
6d80: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
6d90: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
6da0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
6db0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
6dc0: 65 72 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73  ered vfs modules
6dd0: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
6de0: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
6df0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
6e00: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
6e10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
6e20: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
6e30: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
6e40: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
6e50: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
6e60: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
6e70: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
6e80: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
6e90: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
6ea0: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
6eb0: 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
6ec0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
6ed0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
6ee0: 64 73 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ds in the sqlite
6ef0: 33 5f 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74  3_vfs .** struct
6f00: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
6f10: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
6f20: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
6f30: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
6f40: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
6f50: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
6f60: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
6f70: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
6f80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
6f90: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
6fa0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
6fb0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
6fc0: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
6fd0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
6fe0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
6ff0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
7000: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
7010: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
7020: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
7030: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
7040: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
7050: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
7060: 0a 2a 2a 20 7b 46 31 31 31 34 31 7d 20 53 51 4c  .** {F11141} SQL
7070: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74  ite will guarant
7080: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  ee that the zFil
7090: 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73  ename string pas
70a0: 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28  sed to.** xOpen(
70b0: 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68  ) is a full path
70c0: 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65  name as generate
70d0: 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61  d by xFullPathna
70e0: 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74  me() and.** that
70f0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
7100: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
7110: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
7120: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
7130: 6c 65 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74  led.  {END} So t
7140: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7150: 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f  ] can store a po
7160: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
7170: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
7180: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
7190: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
71a0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
71b0: 2a 0a 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 68  *.** {F11142} Th
71c0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
71d0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
71e0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
71f0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
7200: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
7210: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
7220: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
7230: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
7240: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
7250: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
7260: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
7270: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
7280: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
7290: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
72a0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e  PEN_CREATE]. {EN
72b0: 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  D}.** If xOpen()
72c0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
72d0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
72e0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
72f0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
7300: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
7310: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
7320: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
7330: 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a  may be.** set..*
7340: 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53  * .** {F11143} S
7350: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
7360: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
7370: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
7380: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
7390: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
73a0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
73b0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20  eing opened:.** 
73c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
73d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
73e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
73f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
7400: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
7410: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7420: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
7430: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7440: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
7450: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7460: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
7470: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
7480: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
7490: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
74a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
74b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f  R_JOURNAL].** </
74c0: 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
74d0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
74e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
74f0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
7500: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
7510: 63 68 61 6e 67 65 73 20 74 68 65 20 77 61 79 20  changes the way 
7520: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
7530: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
7540: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
7550: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
7560: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
7570: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
7580: 72 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68 74 20  rollback, might 
7590: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
75a0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
75b0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
75c0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
75d0: 6e 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73 6f 20  nal are.** also 
75e0: 61 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20 61 74  a no-op.  Any at
75f0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
7600: 65 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75 72 6e  e journal return
7610: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 0a 2a   SQLITE_IOERR..*
7620: 2a 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65  * Or the impleme
7630: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
7640: 63 6f 67 6e 69 7a 65 20 74 68 65 20 61 20 64 61  cognize the a da
7650: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7660: 0a 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70 61 67  .** be doing pag
7670: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
7680: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
7690: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20 6f 72  s in a random or
76a0: 64 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74 20 75  der.** and set u
76b0: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
76c0: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
76d0: 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  .** .** SQLite m
76e0: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
76f0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
7700: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
7710: 78 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a  xOpen.** method:
7720: 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
7730: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
7740: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7750: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7760: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7770: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
7780: 20 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53   {F11145} The [S
7790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
77a0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
77b0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
77c0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
77d0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
77e0: 6f 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20  osed.  {F11146} 
77f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7800: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
7810: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
7820: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
7830: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
7840: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
7850: 2e 20 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54  . .** {F11147} T
7860: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
7870: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
7880: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
7890: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a  hould be opened.
78a0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
78b0: 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66   access.  This f
78c0: 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61  lag is set for a
78d0: 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a  ll files except.
78e0: 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20  ** for the main 
78f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 7b  database file. {
7900: 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  END}.** .** {F11
7910: 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a  148} At least sz
7920: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
7930: 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
7940: 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 0a 2a  ted by SQLite .*
7950: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
7960: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
7970: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
7980: 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20  s the third .** 
7990: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
79a0: 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  n.  {END}  The x
79b0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
79c0: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
79d0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
79e0: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
79f0: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
7a00: 6e 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34  n..** .** {F1114
7a10: 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  9} The flags arg
7a20: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
7a30: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
7a40: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
7a50: 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72   .** to test for
7a60: 20 74 68 65 20 65 78 69 73 74 61 6e 63 65 20 6f   the existance o
7a70: 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20  f a file,.** or 
7a80: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
7a90: 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65 73  EADWRITE] to tes
7aa0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
7ab0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
7ac0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
7ad0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
7ae0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
7af0: 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66  st to see if a f
7b00: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
7b10: 72 65 61 64 61 62 6c 65 2e 20 20 7b 45 4e 44 7d  readable.  {END}
7b20: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
7b30: 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79   a .** directory
7b40: 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 35 30  ..** .** {F11150
7b50: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
7b60: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
7b70: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
7b80: 65 2b 31 20 62 79 74 65 20 66 6f 72 0a 2a 2a 20  e+1 byte for.** 
7b90: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
7ba0: 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70 6e  rs for xGetTempn
7bb0: 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61 74  ame and xFullPat
7bc0: 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31 7d 20  hname. {F11151} 
7bd0: 54 68 65 20 65 78 61 63 74 0a 2a 2a 20 73 69 7a  The exact.** siz
7be0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
7bf0: 62 75 66 66 65 72 20 69 73 20 61 6c 73 6f 20 70  buffer is also p
7c00: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
7c10: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 0a 2a 2a  eter to both .**
7c20: 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20   methods. {END} 
7c30: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
7c40: 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61 72 67  ffer is not larg
7c50: 65 20 65 6e 6f 75 67 68 2c 20 53 51 4c 49 54 45  e enough, SQLITE
7c60: 5f 43 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73 68 6f  _CANTOPEN.** sho
7c70: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
7c80: 20 41 73 20 74 68 69 73 20 69 73 20 68 61 6e 64   As this is hand
7c90: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
7ca0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 0a  rror by SQLite,.
7cb0: 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  ** vfs implement
7cc0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
7cd0: 64 65 61 76 6f 72 20 74 6f 20 70 72 65 76 65 6e  deavor to preven
7ce0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
7cf0: 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61 6d 65  g .** mxPathname
7d00: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
7d10: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
7d20: 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ** .** The xRand
7d30: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
7d40: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
7d50: 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65  Time() interface
7d60: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72  s.** are not str
7d70: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
7d80: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
7d90: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
7da0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
7db0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
7dc0: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
7dd0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
7de0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
7df0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
7e00: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
7e10: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
7e20: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
7e30: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
7e40: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
7e50: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
7e60: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
7e70: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
7e80: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70  .  The.** xSleep
7e90: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 20  () method cause 
7ea0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
7eb0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
7ec0: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
7ed0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
7ee0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54  econds given.  T
7ef0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
7f00: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7f10: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
7f20: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
7f30: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
7f40: 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70  .** time..*/.typ
7f50: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7f60: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
7f70: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  vfs;.struct sqli
7f80: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
7f90: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
7fa0: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
7fb0: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
7fc0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
7fd0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
7fe0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
7ff0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
8000: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
8010: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
8020: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
8030: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
8040: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
8050: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
8060: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
8070: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
8080: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
8090: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
80a0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
80b0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
80c0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
80d0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
80e0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
80f0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
8100: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
8110: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
8120: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
8130: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
8140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
8150: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
8160: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
8170: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
8180: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
8190: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
81a0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
81b0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
81c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
81d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
81e0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
81f0: 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28 73 71  xGetTempname)(sq
8200: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
8210: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
8220: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
8230: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
8240: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
8250: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
8260: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
8270: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
8280: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8290: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
82a0: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
82b0: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
82c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
82d0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
82e0: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28  rMsg);.  void *(
82f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
8300: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
8310: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
8320: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
8330: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
8340: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
8350: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
8360: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8370: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
8380: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
8390: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
83a0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
83b0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
83c0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
83d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
83e0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66  le*);.  /* New f
83f0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
8400: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
8410: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
8420: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
8430: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
8440: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
8450: 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a  happens. */.};..
8460: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8470: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
8480: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
8490: 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20   {F11190}.**.** 
84a0: 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65 20 69  {F11191} These i
84b0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
84c0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
84d0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
84e0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
84f0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
8500: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
8510: 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20   object. {END}  
8520: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
8530: 2a 20 74 68 65 20 6b 69 6e 64 20 6f 66 20 77 68  * the kind of wh
8540: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
8550: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
8560: 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20  ss method is.** 
8570: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46  looking for.  {F
8580: 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49  11192} With SQLI
8590: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
85a0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
85b0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
85c0: 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20  hecks to see if 
85d0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
85e0: 20 7b 46 31 31 31 39 33 7d 20 57 69 74 68 0a 2a   {F11193} With.*
85f0: 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  * SQLITE_ACCESS_
8600: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
8610: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68  Access method ch
8620: 65 63 6b 73 20 74 6f 20 73 65 65 0a 2a 2a 20 69  ecks to see.** i
8630: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f  f the file is bo
8640: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
8650: 77 72 69 74 61 62 6c 65 2e 20 20 7b 46 31 31 31  writable.  {F111
8660: 39 34 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49  94} With.** SQLI
8670: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 74  TE_ACCESS_READ t
8680: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8690: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f 20 73  d.** checks to s
86a0: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ee if the file i
86b0: 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23  s readable..*/.#
86c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
86d0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
86e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
86f0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8700: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
8710: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
8720: 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     2../*.** CAPI
8730: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
8740: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
8750: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46   Result Codes {F
8760: 31 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12200}.**.** The
8770: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
8780: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
8790: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
87a0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
87b0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
87c0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
87d0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
87e0: 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
87f0: 65 2e 0a 2a 2a 20 54 68 65 20 65 78 74 65 6e 64  e..** The extend
8800: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
8810: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
8820: 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
8830: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
8840: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 43  ibility..**.** C
8850: 4f 56 45 4e 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  OVENANTS:.**.** 
8860: 7b 46 31 32 32 30 31 7d 20 4e 65 77 20 5b 73 71  {F12201} New [sq
8870: 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73 65  lite3 | database
8880: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 68 61   connections] ha
8890: 76 65 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ve the .**      
88a0: 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52      [SQLITE_IOER
88b0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
88c0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
88d0: 66 65 61 74 75 72 65 0a 2a 2a 20 20 20 20 20 20  feature.**      
88e0: 20 20 20 20 64 69 73 61 62 6c 65 64 20 62 79 20      disabled by 
88f0: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
8900: 46 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c  F12202} The [sql
8910: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
8920: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 69 6e  sult_codes()] in
8930: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 65 6e 61  terface will ena
8940: 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
8950: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
8960: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
8970: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20  sult codes] for 
8980: 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
8990: 20 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74 61   [sqlite3 | data
89a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
89b0: 20 69 6e 20 69 74 73 20 31 73 74 20 70 61 72 61   in its 1st para
89c0: 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
89d0: 20 20 69 66 20 74 68 65 20 32 6e 64 20 70 61 72    if the 2nd par
89e0: 61 6d 65 74 65 72 20 69 74 20 74 72 75 65 2c 20  ameter it true, 
89f0: 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20  or disable them 
8a00: 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
8a10: 20 20 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72     2nd parameter
8a20: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
8a30: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
8a40: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
8a50: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
8a60: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
8a70: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
8a80: 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30  rt Rowid {F12220
8a90: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  }.**.** Each ent
8aa0: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
8ab0: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
8ac0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
8ad0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
8ae0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
8af0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
8b00: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
8b10: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
8b20: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
8b30: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
8b40: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
8b50: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
8b60: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
8b70: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
8b80: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
8b90: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
8ba0: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
8bb0: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
8bc0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
8bd0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
8be0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6e  ** is another an
8bf0: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
8c00: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
8c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8c20: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
8c30: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
8c40: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
8c50: 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  RT into the data
8c60: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61  base from the da
8c70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8c80: 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68  n.** shown in th
8c90: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
8ca0: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
8cb0: 66 75 6c 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68  ful inserts.** h
8cc0: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
8cd0: 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61  d on this databa
8ce0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
8cf0: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
8d00: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53  .**.** If an INS
8d10: 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69  ERT occurs withi
8d20: 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
8d30: 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  n the rowid of t
8d40: 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72  he.** inserted r
8d50: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
8d60: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
8d70: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
8d80: 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e  igger.** is runn
8d90: 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74  ing.  But once t
8da0: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
8db0: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
8dc0: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
8dd0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
8de0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
8df0: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
8e00: 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72  before the.** tr
8e10: 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
8e20: 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61  ** An INSERT tha
8e30: 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
8e40: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
8e50: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
8e60: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73  * successful ins
8e70: 65 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ert and does not
8e80: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
8e90: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
8ea0: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
8eb0: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
8ec0: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
8ed0: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
8ee0: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
8ef0: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
8f00: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
8f10: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
8f20: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
8f30: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
8f40: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
8f50: 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52  ils.  When INSER
8f60: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a  T OR REPLACE .**
8f70: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
8f80: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
8f90: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
8fa0: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
8fb0: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
8fc0: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
8fd0: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
8fe0: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
8ff0: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
9000: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
9010: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
9020: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
9030: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
9040: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
9050: 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72  face. .**.** For
9060: 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
9070: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
9080: 6e 20 69 6e 73 65 72 74 20 69 73 20 63 6f 6e 73  n insert is cons
9090: 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
90a0: 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
90b0: 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
90c0: 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
90d0: 6b 2e 0a 2a 2a 0a 2a 2a 20 43 4f 56 45 4e 41 4e  k..**.** COVENAN
90e0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32  TS:.**.** {F1222
90f0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
9100: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
9110: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
9120: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
9130: 20 20 20 20 20 20 72 6f 77 69 64 20 6f 66 20 74        rowid of t
9140: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
9150: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74  uccessful insert
9160: 20 64 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20   done.**        
9170: 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61    on the same da
9180: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9190: 6e 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65  n and within the
91a0: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
91b0: 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
91c0: 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68  t, or zero if th
91d0: 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20  ere have.**     
91e0: 20 20 20 20 20 62 65 65 6e 20 6e 6f 20 71 75 61       been no qua
91f0: 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 20  lifying inserts 
9200: 6f 6e 20 74 68 61 74 20 63 6f 6e 6e 65 63 74 69  on that connecti
9210: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32  on..**.** {F1222
9220: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
9230: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
9240: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
9250: 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
9260: 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65    same value whe
9270: 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
9280: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
9290: 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  ontext.**       
92a0: 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62     immediately b
92b0: 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20  efore and after 
92c0: 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a  a ROLLBACK..**.*
92d0: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
92e0: 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d 20 49 66  *.** {U12232} If
92f0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
9300: 20 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65   does a new inse
9310: 72 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  rt on the same.*
9320: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
9330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
9340: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
9350: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
9360: 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  wid()].**       
9370: 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72     function is r
9380: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
9390: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
93a0: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
93b0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
93c0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
93d0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
93e0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
93f0: 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
9400: 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65     unpredictable
9410: 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
9420: 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
9430: 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
9440: 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20  *          last 
9450: 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f  insert rowid..*/
9460: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
9470: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
9480: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
9490: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
94a0: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
94b0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
94c0: 64 69 66 69 65 64 20 7b 46 31 32 32 34 30 7d 0a  dified {F12240}.
94d0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
94e0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
94f0: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
9500: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
9510: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
9520: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
9530: 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
9540: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
9550: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
9560: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65  .** on the conne
9570: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
9580: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
9590: 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a  ameter.  Only.**
95a0: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
95b0: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
95c0: 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45  fied by the INSE
95d0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a  RT, UPDATE, or.*
95e0: 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
95f0: 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
9600: 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
9610: 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
9620: 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74  triggers are not
9630: 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68   counted. Use th
9640: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
9650: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
9660: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  tion.** to find 
9670: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
9680: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c   of changes incl
9690: 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
96a0: 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
96b0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63  ..**.** A "row c
96c0: 68 61 6e 67 65 73 22 20 69 73 20 61 20 63 68 61  hanges" is a cha
96d0: 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
96e0: 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
96f0: 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
9700: 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
9710: 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
9720: 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
9730: 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
9740: 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
9750: 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20  ects of REPLACE 
9760: 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
9770: 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
9780: 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
9790: 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45  sing, DROP TABLE
97a0: 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
97b0: 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
97c0: 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
97d0: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
97e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  es..**.** A "tri
97f0: 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
9800: 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
9810: 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
9820: 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
9830: 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
9840: 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73   a trigger.  Mos
9850: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
9860: 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
9870: 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
9880: 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
9890: 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
98a0: 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
98b0: 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
98c0: 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
98d0: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
98e0: 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
98f0: 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
9900: 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
9910: 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
9920: 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
9930: 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
9940: 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
9950: 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
9960: 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73  **.** Calling [s
9970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
9980: 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
9990: 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
99a0: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
99b0: 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
99c0: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54  context..**.** T
99d0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
99e0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
99f0: 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
9a00: 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
9a10: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
9a20: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
9a30: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
9a40: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
9a50: 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
9a60: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65  xt..**.** So whe
9a70: 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
9a80: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
9a90: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
9aa0: 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
9ab0: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
9ac0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
9ad0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
9ae0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
9af0: 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
9b00: 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
9b10: 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62  .** Within the b
9b20: 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
9b30: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  , the sqlite3_ch
9b40: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
9b50: 65 0a 2a 2a 20 63 61 6e 20 62 65 20 63 61 6c 6c  e.** can be call
9b60: 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
9b70: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
9b80: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
9b90: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
9ba0: 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
9bb0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
9bc0: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
9bd0: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
9be0: 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
9bf0: 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
9c00: 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
9c10: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
9c20: 69 6e 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  in changes.** ca
9c30: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
9c40: 65 72 73 20 73 69 6e 63 65 20 74 68 65 79 20 68  ers since they h
9c50: 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
9c60: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ntext..**.** SQL
9c70: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
9c80: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
9c90: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
9ca0: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52  ithout.** a WHER
9cb0: 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70  E clause by drop
9cc0: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
9cd0: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
9ce0: 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a  (This is much.**
9cf0: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
9d00: 6e 67 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ng through and d
9d10: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
9d20: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d  al elements from
9d30: 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20   the.** table.) 
9d40: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
9d50: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
9d60: 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 0a  he deletions in.
9d70: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
9d80: 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
9d90: 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 20 77  ow changes and w
9da0: 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74  ill not be count
9db0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 73 71 6c  ed.** by the sql
9dc0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
9dd0: 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
9de0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
9df0: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65 74  tions..** To get
9e00: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
9e10: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
9e20: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
9e30: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
9e40: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
9e50: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
9e60: 0a 2a 2a 20 43 4f 56 45 4e 41 4e 54 53 3a 0a 2a  .** COVENANTS:.*
9e70: 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68  *.** {F12241} Th
9e80: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
9e90: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  es()] function r
9ea0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
9eb0: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
9ec0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
9ed0: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
9ee0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
9ef0: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
9f00: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
9f10: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
9f20: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
9f30: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
9f40: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
9f50: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
9f60: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
9f70: 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a  if there have.**
9f80: 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65            not be
9f90: 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e  en any qualifyin
9fa0: 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  g row changes..*
9fb0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
9fc0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d  :.**.** {U12252}
9fd0: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
9fe0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
9ff0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
a000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a010: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
a020: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
a030: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
a040: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
a050: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
a060: 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72           is unpr
a070: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 75 6e  edictable and un
a080: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
a090: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
a0a0: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
a0b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
a0c0: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
a0d0: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31  ows Modified {F1
a0e0: 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69  2260}.***.** Thi
a0f0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
a100: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
a110: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
a120: 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54  sed.** by INSERT
a130: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
a140: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
a150: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
a160: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f   handle.** was o
a170: 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f 75 6e  pened.  The coun
a180: 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  t includes all c
a190: 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20  hanges from all 
a1a0: 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65  trigger.** conte
a1b0: 78 74 73 2e 20 20 42 75 74 20 74 68 65 20 63 6f  xts.  But the co
a1c0: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
a1d0: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
a1e0: 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  d to.** implemen
a1f0: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
a200: 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61  aints, do rollba
a210: 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
a220: 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44  cessing,.** or D
a230: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
a240: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
a250: 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  nges.** are coun
a260: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
a270: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
a280: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
a290: 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77  completed .** (w
a2a0: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
a2b0: 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73  t handle is pass
a2c0: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
a2d0: 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b  eset()] or .** [
a2e0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
a2f0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ()])..**.** SQLi
a300: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
a310: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
a320: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
a330: 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45  thout.** a WHERE
a340: 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70   clause by dropp
a350: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
a360: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
a370: 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20  This is much.** 
a380: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
a390: 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64  g.** through and
a3a0: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
a3b0: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f  dual elements fo
a3c0: 72 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20  rm the table.)  
a3d0: 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68  Because of.** th
a3e0: 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  is optimization,
a3f0: 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e   the change coun
a400: 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52  t for "DELETE FR
a410: 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62  OM table" will b
a420: 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64  e.** zero regard
a430: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
a440: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
a450: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
a460: 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61  lly in the.** ta
a470: 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61  ble. To get an a
a480: 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
a490: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
a4a0: 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
a4b0: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
a4c0: 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
a4d0: 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53  instead..**.** S
a4e0: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
a4f0: 69 74 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 69  ite3_change()] i
a500: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
a510: 43 4f 56 45 4e 41 4e 54 53 3a 0a 2a 2a 20 0a 2a  COVENANTS:.** .*
a520: 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20 5b  * {F12261} The [
a530: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
a540: 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
a550: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
a560: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
a570: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
a580: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
a590: 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
a5a0: 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
a5b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
a5c0: 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33  he same [sqlite3
a5d0: 20 7c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   | database conn
a5e0: 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a  ection], in any.
a5f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67  **          trig
a600: 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e  ger context, sin
a610: 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
a620: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a 2a  connection was.*
a630: 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74  *          creat
a640: 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ed..**.** LIMITA
a650: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
a660: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
a670: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
a680: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
a690: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
a6a0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
a6b0: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
a6c0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
a6d0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
a6e0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 0a  then the value .
a6f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
a700: 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
a710: 74 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65 61 6e  table and unmean
a720: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
a730: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
a740: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
a750: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a760: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
a770: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20  g-Running Query 
a780: 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12270}.**.** T
a790: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
a7a0: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
a7b0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
a7c0: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
a7d0: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
a7e0: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
a7f0: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
a800: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
a810: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
a820: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
a830: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
a840: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
a850: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
a860: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
a870: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
a880: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
a890: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
a8a0: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
a8b0: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
a8c0: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
a8d0: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
a8e0: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
a8f0: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
a900: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
a910: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
a920: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
a930: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
a940: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
a950: 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  e with a databas
a960: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
a970: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
a980: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
a990: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
a9a0: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
a9b0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51  ..**.** If an SQ
a9c0: 4c 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  L is very nearly
a9d0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
a9e0: 20 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69 74   time when sqlit
a9f0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a 2a  e3_interrupt().*
aa00: 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  * is called, the
aa10: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
aa20: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
aa30: 74 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ty to be interru
aa40: 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67 68  pted..** It migh
aa50: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
aa60: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20  mpletion..** An 
aa70: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
aa80: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
aa90: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  d will return.**
aaa0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
aab0: 50 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e 74  PT].  If the int
aac0: 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
aad0: 72 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20  ration is an.** 
aae0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
aaf0: 6f 72 20 44 45 4c 45 54 45 20 74 68 61 74 20 69  or DELETE that i
ab00: 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
ab10: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
ab20: 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 65  , .** then the e
ab30: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
ab40: 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  n will be rolled
ab50: 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
ab60: 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  lly..** A call t
ab70: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
ab80: 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
ab90: 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
aba0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
abb0: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
abc0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
abd0: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
abe0: 2a 2a 20 43 4f 56 45 4e 41 4e 54 53 3a 0a 2a 2a  ** COVENANTS:.**
abf0: 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54 68 65  .** {F12271} The
ac00: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
ac10: 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  upt()] interface
ac20: 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20   will force all 
ac30: 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  running.**      
ac40: 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
ac50: 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
ac60: 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  th the same data
ac70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
ac80: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 68  **          to h
ac90: 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65 73  alt after proces
aca0: 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65  sing at most one
acb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20   additional row 
acc0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  of.**          d
acd0: 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ata..**.** {F122
ace0: 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74  72} Any SQL stat
acf0: 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e  ement that is in
ad00: 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71  terrupted by [sq
ad10: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ad20: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
ad30: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
ad40: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
ad50: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
ad60: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39 7d  :.**.** {U12279}
ad70: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
ad80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
ad90: 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
ada0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
adb0: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75  *          is ru
adc0: 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
add0: 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
ade0: 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
adf0: 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
ae00: 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
ae10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ae20: 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
ae30: 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
ae40: 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35 31   Complete {F1051
ae50: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
ae60: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
ae70: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
ae80: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
ae90: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
aea0: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
aeb0: 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
aec0: 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61   form complete a
aed0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
aee0: 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
aef0: 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
af00: 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
af10: 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
af20: 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
af30: 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f  rsing.  These ro
af40: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72  utines return tr
af50: 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  ue if the input 
af60: 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
af70: 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
af80: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
af90: 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
afa0: 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
afb0: 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
afc0: 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
afd0: 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
afe0: 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65   is not a fragme
aff0: 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54  nt of a.** CREAT
b000: 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
b010: 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73  ent.  Semicolons
b020: 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
b030: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
b040: 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
b050: 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
b060: 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
b070: 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
b080: 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
b090: 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
b0a0: 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
b0b0: 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
b0c0: 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
b0d0: 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
b0e0: 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
b0f0: 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  t terminator..**
b100: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
b110: 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
b120: 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a 20 73  the SQL and.** s
b130: 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  o will not detec
b140: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
b150: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
b160: 2a 0a 2a 2a 20 43 4f 56 45 4e 41 4e 54 53 3a 0a  *.** COVENANTS:.
b170: 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54  **.** {F10511} T
b180: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  he sqlite3_compl
b190: 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ete() and sqlite
b1a0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 66  3_complete16() f
b1b0: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20  unctions.**     
b1c0: 20 20 20 20 20 72 65 74 75 72 6e 20 74 72 75 65       return true
b1d0: 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 61   (non-zero) if a
b1e0: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c  nd only if the l
b1f0: 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
b200: 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 20 74  non-whitespace t
b210: 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e  oken in their in
b220: 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  put is a semicol
b230: 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  on that.**      
b240: 20 20 20 20 69 73 20 6e 6f 74 20 69 6e 20 62 65      is not in be
b250: 74 77 65 65 6e 20 74 68 65 20 42 45 47 49 4e 20  tween the BEGIN 
b260: 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45  and END of a CRE
b270: 41 54 45 20 54 52 49 47 47 45 52 0a 2a 2a 20 20  ATE TRIGGER.**  
b280: 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
b290: 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  t..**.** LIMITAT
b2a0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30  IONS:.**.** {U10
b2b0: 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74  512} The input t
b2c0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  o sqlite3_comple
b2d0: 74 65 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a  te() must be a z
b2e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
b2f0: 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
b300: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
b310: 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75  U10513} The inpu
b320: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  t to sqlite3_com
b330: 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74 20 62  plete16() must b
b340: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
b350: 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
b360: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
b370: 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
b380: 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
b390: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
b3a0: 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
b3b0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
b3c0: 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
b3d0: 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
b3e0: 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
b3f0: 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
b400: 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
b410: 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33 31 30  Y Errors {F12310
b420: 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
b430: 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73 20  tine identifies 
b440: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
b450: 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
b460: 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  e.** invoked whe
b470: 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70 74  never an attempt
b480: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
b490: 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
b4a0: 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68  e .** that anoth
b4b0: 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72 6f  er thread or pro
b4c0: 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
b4d0: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
b4e0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
b4f0: 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
b500: 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
b510: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
b520: 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
b530: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
b540: 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
b550: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74  he lock..** If t
b560: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
b570: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
b580: 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61  en the.** callba
b590: 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  ck will be invok
b5a0: 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
b5b0: 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66  ments.  The.** f
b5c0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
b5d0: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
b5e0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
b5f0: 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
b600: 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
b610: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
b620: 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65  is routine.  The
b630: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
b640: 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
b650: 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
b660: 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
b670: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
b680: 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
b690: 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
b6a0: 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 20 49 66  king event.   If
b6b0: 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
b6c0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
b6d0: 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
b6e0: 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
b6f0: 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
b700: 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
b710: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
b720: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
b730: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
b740: 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74  eturned..** If t
b750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
b760: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
b770: 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
b780: 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
b790: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
b7a0: 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
b7b0: 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
b7c0: 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
b7d0: 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
b7e0: 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
b7f0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
b800: 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65  at.** it will be
b810: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
b820: 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
b830: 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51  ention..** If SQ
b840: 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
b850: 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
b860: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
b870: 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a  ould result in.*
b880: 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  * a deadlock, it
b890: 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
b8a0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
b8b0: 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53  E_BUSY] or.** [S
b8c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
b8d0: 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
b8e0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a 20  invoking the.** 
b8f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
b900: 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
b910: 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
b920: 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
b930: 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
b940: 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
b950: 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
b960: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
b970: 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
b980: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
b990: 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
b9a0: 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
b9b0: 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
b9c0: 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
b9d0: 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
b9e0: 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
b9f0: 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
ba00: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
ba10: 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
ba20: 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
ba30: 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
ba40: 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
ba50: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
ba60: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
ba70: 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
ba80: 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
ba90: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
baa0: 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
bab0: 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
bac0: 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
bad0: 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
bae0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
baf0: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
bb00: 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
bb10: 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
bb20: 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
bb30: 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
bb40: 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
bb50: 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
bb60: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
bb70: 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
bb80: 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
bb90: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
bba0: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  L..**.** The [SQ
bbb0: 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
bbc0: 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
bbd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
bbe0: 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
bbf0: 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
bc00: 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
bc10: 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
bc20: 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
bc30: 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
bc40: 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
bc50: 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
bc60: 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
bc70: 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
bc80: 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
bc90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
bca0: 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
bcb0: 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
bcc0: 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
bcd0: 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
bce0: 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
bcf0: 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
bd00: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
bd10: 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
bd20: 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
bd30: 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20  ders.  If it is 
bd40: 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
bd50: 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
bd60: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
bd70: 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
bd80: 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
bd90: 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
bda0: 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
bdb0: 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
bdc0: 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
bdd0: 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
bde0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
bdf0: 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
be00: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
be10: 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20  BLOCKED].  This 
be20: 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
be30: 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
be40: 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
be50: 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
be60: 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
be70: 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f   <a href="http:/
be80: 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f  /www.sqlite.org/
be90: 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
bea0: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
beb0: 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
bec0: 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
bed0: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
bee0: 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
bef0: 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
bf00: 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
bf10: 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a  mportant..**..**
bf20: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
bf30: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
bf40: 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
bf50: 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
bf60: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
bf70: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
bf80: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
bf90: 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75  ears any previou
bfa0: 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74 65 20  s one. .** Note 
bfb0: 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
bfc0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
bfd0: 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20  ut()] will also 
bfe0: 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20  set or clear.** 
bff0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
c000: 2e 0a 2a 2a 0a 2a 2a 20 43 4f 56 45 4e 41 4e 54  ..**.** COVENANT
c010: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31  S:.**.** {F12311
c020: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
c030: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66  usy_handler()] f
c040: 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
c050: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c060: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  r.**          ca
c070: 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 64 61  llback in the da
c080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c090: 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  n identified by 
c0a0: 74 68 65 20 31 73 74 0a 2a 2a 20 20 20 20 20 20  the 1st.**      
c0b0: 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69      parameter wi
c0c0: 74 68 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  th a new busy ha
c0d0: 6e 64 6c 65 72 20 69 64 65 6e 74 69 66 69 65 64  ndler identified
c0e0: 20 62 79 20 74 68 65 20 32 6e 64 20 61 6e 64 20   by the 2nd and 
c0f0: 33 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  3rd.**          
c100: 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a  parameters..**.*
c110: 2a 20 7b 46 31 32 33 31 32 7d 20 54 68 65 20 64  * {F12312} The d
c120: 65 66 61 75 6c 74 20 62 75 73 79 20 68 61 6e 64  efault busy hand
c130: 6c 65 72 20 66 6f 72 20 6e 65 77 20 64 61 74 61  ler for new data
c140: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
c150: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
c160: 7b 46 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77  {F12314} When tw
c170: 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61  o or more databa
c180: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
c190: 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63  are a common cac
c1a0: 68 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he,.**          
c1b0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
c1c0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
c1d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72  e connection cur
c1e0: 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20  rently using.** 
c1f0: 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 63           the cac
c200: 68 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  he is invoked wh
c210: 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63  en the cache enc
c220: 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a  ounters a lock..
c230: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49  **.** {F12316} I
c240: 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
c250: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
c260: 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  s zero, then the
c270: 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20   SQLite.**      
c280: 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 74 68      interface th
c290: 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
c2a0: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 77 69  locking event wi
c2b0: 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  ll return.**    
c2c0: 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 55        [SQLITE_BU
c2d0: 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  SY]..**.** {F123
c2e0: 31 38 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  18} SQLite will 
c2f0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79  invokes the busy
c300: 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77   handler with tw
c310: 6f 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  o argument which
c320: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
c330: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
c340: 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20  ointer supplied 
c350: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
c360: 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
c370: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
c380: 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64  y_handler()] and
c390: 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20   a count of the 
c3a0: 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a  number of prior.
c3b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
c3c0: 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  cations of the b
c3d0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
c3e0: 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
c3f0: 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49   event..**.** LI
c400: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
c410: 20 7b 55 31 32 33 31 39 7d 20 41 20 62 75 73 79   {U12319} A busy
c420: 20 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20   handler should 
c430: 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f 73 65 20 74  not call close t
c440: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c450: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
c460: 20 20 20 6f 72 20 70 72 65 70 61 72 65 64 20 73     or prepared s
c470: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 6e  tatement that in
c480: 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
c490: 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
c4a0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
c4b0: 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
c4c0: 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
c4d0: 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
c4e0: 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
c4f0: 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 46 31  Busy Timeout {F1
c500: 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2340}.**.** This
c510: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
c520: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
c530: 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
c540: 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c  dler].** that sl
c550: 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65  eeps for a while
c560: 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65   when a.** table
c570: 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65   is locked.  The
c580: 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c   handler will sl
c590: 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
c5a0: 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20  es until .** at 
c5b0: 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
c5c0: 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
c5d0: 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f  ing have been do
c5e0: 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20 41 66 74  ne. {F12343} Aft
c5f0: 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69  er.** "ms" milli
c600: 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
c610: 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72  ing, the handler
c620: 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
c630: 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69  .** causes [sqli
c640: 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
c650: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
c660: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
c670: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
c680: 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
c690: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
c6a0: 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
c6b0: 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
c6c0: 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
c6d0: 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
c6e0: 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  lers..**.** Ther
c6f0: 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
c700: 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
c710: 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
c720: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
c730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66   connection.  If
c740: 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
c750: 6e 64 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65  ndler was define
c760: 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73  d  .** (using [s
c770: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
c780: 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
c790: 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
c7a0: 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
c7b0: 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
c7c0: 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a  r is cleared..**
c7d0: 0a 2a 2a 20 43 4f 56 45 4e 41 4e 54 53 3a 0a 2a  .** COVENANTS:.*
c7e0: 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68  *.** {F12341} Th
c7f0: 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
c800: 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74  timeout()] funct
c810: 69 6f 6e 20 6f 76 65 72 72 69 64 65 73 20 61 6e  ion overrides an
c820: 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  y prior.**      
c830: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
c840: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20  y_timeout()] or 
c850: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
c860: 6e 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67  ndler()] setting
c870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
c880: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
c890: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
c8a0: 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20  .** {F12343} If 
c8b0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
c8c0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
c8d0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
c8e0: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
c8f0: 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20         or equal 
c900: 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  to zero, then th
c910: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
c920: 73 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61  s cleared so tha
c930: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  t.**          al
c940: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63  l subsequent loc
c950: 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65  king events imme
c960: 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b  diately return [
c970: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
c980: 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20  .** {F12344} If 
c990: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
c9a0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
c9b0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
c9c0: 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20   a positive.**  
c9d0: 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e          number N
c9e0: 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61  , then a busy ha
c9f0: 6e 64 6c 65 72 20 69 73 20 73 65 74 20 74 68 61  ndler is set tha
ca00: 74 20 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c  t repeatedly cal
ca10: 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ls.**          t
ca20: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
ca30: 6f 64 20 69 6e 20 74 68 65 20 56 46 53 20 69 6e  od in the VFS in
ca40: 74 65 72 66 61 63 65 20 75 6e 74 69 6c 20 65 69  terface until ei
ca50: 74 68 65 72 20 74 68 65 0a 2a 2a 20 20 20 20 20  ther the.**     
ca60: 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73       lock clears
ca70: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75   or until the cu
ca80: 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74  mulative sleep t
ca90: 69 6d 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ime reported bac
caa0: 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  k.**          by
cab0: 20 78 53 6c 65 65 70 28 29 20 65 78 63 65 65 64   xSleep() exceed
cac0: 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  s N milliseconds
cad0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
cae0: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
caf0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
cb00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cb10: 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
cb20: 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
cb30: 6e 67 20 51 75 65 72 69 65 73 20 7b 46 31 32 33  ng Queries {F123
cb40: 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  70}.**.** Defini
cb50: 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
cb60: 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
cb70: 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
cb80: 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
cb90: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
cba0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
cbb0: 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
cbc0: 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
cbd0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
cbe0: 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
cbf0: 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
cc00: 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
cc10: 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
cc20: 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
cc30: 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
cc40: 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
cc50: 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
cc60: 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
cc70: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
cc80: 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
cc90: 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
cca0: 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
ccb0: 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
ccc0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
ccd0: 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
cce0: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
ccf0: 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
cd00: 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
cd10: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
cd20: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
cd30: 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
cd40: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 28 4e  s.  There are (N
cd50: 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
cd60: 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 0a 2a  n the array.  .*
cd70: 2a 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f  * The first M po
cd80: 69 6e 74 65 72 73 20 70 6f 69 6e 74 20 74 6f 20  inters point to 
cd90: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
cda0: 73 74 72 69 6e 67 73 20 74 68 61 74 20 0a 2a 2a  strings that .**
cdb0: 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
cdc0: 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
cdd0: 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
cde0: 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
cdf0: 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
ce00: 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a  esults.  NULL.**
ce10: 20 76 61 6c 75 65 73 20 61 72 65 20 67 69 76 65   values are give
ce20: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
ce30: 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
ce40: 65 73 20 61 72 65 20 69 6e 0a 2a 2a 20 74 68 65  es are in.** the
ce50: 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
ce60: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
ce70: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
ce80: 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
ce90: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
cea0: 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
ceb0: 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
cec0: 69 67 68 74 20 63 6f 6e 73 69 73 74 73 20 6f 66  ight consists of
ced0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
cee0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
cef0: 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
cf00: 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
cf10: 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
cf20: 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
cf30: 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
cf40: 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
cf50: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
cf60: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
cf70: 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
cf80: 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c  .** As an exampl
cf90: 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
cfa0: 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
cfb0: 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
cfc0: 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
cfd0: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
cfe0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
cff0: 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
d000: 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
d010: 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
d020: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
d030: 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
d040: 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
d050: 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
d060: 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
d070: 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
d080: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
d090: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
d0a0: 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
d0b0: 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
d0c0: 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
d0d0: 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
d0e0: 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
d0f0: 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
d100: 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
d110: 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
d120: 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
d130: 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
d140: 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
d150: 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
d160: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
d170: 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
d180: 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
d190: 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
d1a0: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d1b0: 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
d1c0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
d1d0: 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
d1e0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d1f0: 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
d200: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
d210: 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
d220: 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
d230: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
d240: 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
d250: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
d260: 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
d270: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d280: 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
d290: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
d2a0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
d2b0: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
d2c0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
d2d0: 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
d2e0: 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
d2f0: 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
d300: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
d310: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
d320: 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
d330: 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
d340: 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e  eter.  It return
d350: 73 20 61 20 5b 72 65 73 75 6c 74 20 74 61 62 6c  s a [result tabl
d360: 65 5d 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  e] to the.** poi
d370: 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
d380: 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
d390: 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
d3a0: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
d3b0: 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  n has finished u
d3c0: 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c  sing the result,
d3d0: 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70   it should .** p
d3e0: 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ass the pointer 
d3f0: 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  to the result ta
d400: 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ble to sqlite3_f
d410: 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
d420: 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65  rder to .** rele
d430: 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
d440: 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65  hat was malloc-e
d450: 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
d460: 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b  he way the .** [
d470: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
d480: 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
d490: 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
d4a0: 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
d4b0: 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
d4c0: 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
d4d0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
d4e0: 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
d4f0: 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  nly .** [sqlite3
d500: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
d510: 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
d520: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
d530: 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
d540: 2e 0a 2a 2a 0a 2a 2a 20 43 4f 56 45 4e 41 4e 54  ..**.** COVENANT
d550: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31  S:.**.** {F12371
d560: 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
d570: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
d580: 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
d590: 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
d5a0: 20 20 20 20 20 20 20 20 20 69 74 20 66 72 65 65           it free
d5b0: 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
d5c0: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75  le under constru
d5d0: 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68  ction, aborts th
d5e0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75  e.**          qu
d5f0: 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20  ery in process, 
d600: 73 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 71  skips any subseq
d610: 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65  uent queries, se
d620: 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
d630: 20 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70     *resultp outp
d640: 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55  ut pointer to NU
d650: 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b  LL and returns [
d660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
d670: 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66  *.** {F12373} If
d680: 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72   the ncolumn par
d690: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
d6a0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
d6b0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
d6c0: 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
d6d0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d6e0: 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d  )] write the num
d6f0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
d700: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
d710: 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
d720: 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
d730: 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71  ncolumn if the q
d740: 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20  uery is.**      
d750: 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28      successful (
d760: 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
d770: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
d780: 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  K)..**.** {F1237
d790: 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70  4} If the nrow p
d7a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
d7b0: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
d7c0: 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
d7d0: 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
d7e0: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
d7f0: 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e  e()] write the n
d800: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
d810: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
d820: 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
d830: 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e  he query into *n
d840: 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 79  row if the query
d850: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
d860: 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74  successful (if t
d870: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
d880: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a  rns SQLITE_OK)..
d890: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 54  **.** {F12373} T
d8a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
d8b0: 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 6f  table()] functio
d8c0: 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f 6c  n sets its *ncol
d8d0: 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  umn value.**    
d8e0: 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75 6d        to the num
d8f0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
d900: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
d910: 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
d920: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
d930: 20 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c 20   sql parameter, 
d940: 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 68  or to zero if th
d950: 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 68  e query in sql h
d960: 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 20  as an empty.**  
d970: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
d980: 65 74 2e 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  et..**.*/.int sq
d990: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d9a0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
d9b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
d9c0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
d9d0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
d9e0: 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  l,      /* SQL t
d9f0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
da00: 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52 65 73  /.  char ***pRes
da10: 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52 65 73  ult,      /* Res
da20: 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
da30: 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77  y */.  int *nrow
da40: 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
da50: 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
da60: 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
da70: 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f  re */.  int *nco
da80: 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a  lumn,         /*
da90: 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
daa0: 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
dab0: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
dac0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
dad0: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
dae0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
daf0: 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
db00: 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
db10: 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
db20: 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
db30: 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
db40: 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b  ting Functions {
db50: 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17400}.**.** Th
db60: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
db70: 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74   workalikes of t
db80: 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
db90: 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
dba0: 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
dbb0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
dbc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
dbd0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
dbe0: 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
dbf0: 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
dc00: 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
dc10: 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
dc20: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
dc30: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
dc40: 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
dc50: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
dc60: 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
dc70: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
dc80: 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
dc90: 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20 42 6f  e3_free()].   Bo
dca0: 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
dcb0: 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
dcc0: 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
dcd0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
dce0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
dcf0: 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
dd00: 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
dd10: 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
dd20: 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33  **.** In sqlite3
dd30: 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
dd40: 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
dd50: 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
dd60: 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
dd70: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
dd80: 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
dd90: 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
dda0: 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
ddb0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
ddc0: 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
ddd0: 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
dde0: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
ddf0: 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
de00: 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
de10: 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
de20: 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
de30: 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
de40: 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69  rintf().  This i
de50: 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
de60: 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
de70: 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
de80: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
de90: 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
dea0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e  ompatibility.  N
deb0: 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
dec0: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
ded0: 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
dee0: 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
def0: 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
df00: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
df10: 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
df20: 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
df30: 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65   the buffer.  We
df40: 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
df50: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
df60: 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
df70: 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
df80: 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
df90: 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
dfa0: 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
dfb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
dfc0: 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
dfd0: 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
dfe0: 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
dff0: 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
e000: 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  * As long as the
e010: 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
e020: 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
e030: 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
e040: 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
e050: 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
e060: 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
e070: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
e080: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
e090: 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
e0a0: 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
e0b0: 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
e0c0: 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
e0d0: 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
e0e0: 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
e0f0: 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
e100: 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
e110: 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
e120: 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
e130: 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  racters..**.** T
e140: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
e150: 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
e160: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
e170: 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
e180: 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
e190: 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
e1a0: 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
e1b0: 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
e1c0: 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f   usual printf fo
e1d0: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
e1e0: 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
e1f0: 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
e200: 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
e210: 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
e220: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71  ns..**.** The %q
e230: 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
e240: 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
e250: 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
e260: 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
e270: 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
e280: 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
e290: 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
e2a0: 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
e2b0: 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
e2c0: 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
e2d0: 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
e2e0: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20  tring literal.  
e2f0: 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
e300: 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
e310: 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
e320: 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
e330: 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
e340: 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
e350: 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
e360: 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
e370: 20 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20   so some string 
e380: 76 61 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e  variable contain
e390: 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
e3a0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
e3b0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
e3c0: 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
e3d0: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
e3e0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
e3f0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
e400: 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
e410: 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
e420: 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
e430: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
e440: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
e450: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
e460: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
e470: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
e480: 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
e490: 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
e4a0: 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
e4b0: 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
e4c0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
e4d0: 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
e4e0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
e4f0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
e500: 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
e510: 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
e520: 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
e530: 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
e540: 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
e550: 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
e560: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
e570: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
e580: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
e590: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
e5a0: 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
e5b0: 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
e5c0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
e5d0: 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
e5e0: 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
e5f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
e600: 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
e610: 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
e620: 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
e630: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
e640: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
e650: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
e660: 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
e670: 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
e680: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
e690: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
e6a0: 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
e6b0: 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
e6c0: 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
e6d0: 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a  eral rule you.**
e6e0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75   should always u
e6f0: 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
e700: 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
e710: 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
e720: 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61  tring .** litera
e730: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20  l..**.** The %Q 
e740: 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
e750: 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
e760: 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
e770: 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
e780: 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
e790: 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
e7a0: 2e 20 20 4f 72 20 69 66 20 74 68 65 20 70 61 72  .  Or if the par
e7b0: 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 61 72  ameter in the ar
e7c0: 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69  gument.** list i
e7d0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
e7e0: 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
e7f0: 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
e800: 20 28 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65   (without single
e810: 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70  .** quotes) in p
e820: 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f  lace of the %Q o
e830: 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20 53 6f  ption. {END}  So
e840: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
e850: 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
e860: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
e870: 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
e880: 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
e890: 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
e8a0: 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
e8b0: 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
e8c0: 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
e8d0: 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
e8e0: 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
e8f0: 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
e900: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
e910: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
e920: 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
e930: 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
e940: 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
e950: 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
e960: 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
e970: 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
e980: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
e990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
e9a0: 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
e9b0: 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
e9c0: 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
e9d0: 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
e9e0: 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
e9f0: 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
ea00: 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
ea10: 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
ea20: 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
ea30: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
ea40: 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
ea50: 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43  g. {END}.**.** C
ea60: 4f 56 45 4e 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  OVENANTS:.**.** 
ea70: 20 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69    .*/.char *sqli
ea80: 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
ea90: 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
eaa0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
eab0: 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
eac0: 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
ead0: 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
eae0: 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
eaf0: 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
eb00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
eb10: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
eb20: 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46 31  on Subsystem {F1
eb30: 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  7300}.**.** {F17
eb40: 33 30 31 7d 20 54 68 65 20 53 51 4c 69 74 65 20  301} The SQLite 
eb50: 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65  core  uses these
eb60: 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
eb70: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
eb80: 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
eb90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
eba0: 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 22   needs. {END}  "
ebb0: 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
ebc0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
ebd0: 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
ebe0: 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
ebf0: 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
ec00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
ec10: 20 20 54 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73    The.** windows
ec20: 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
ec30: 20 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 72 65 65   malloc and free
ec40: 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
ec50: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ions..**.** {F17
ec60: 33 30 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33  302} The sqlite3
ec70: 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
ec80: 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
ec90: 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
eca0: 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
ecb0: 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
ecc0: 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
ecd0: 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
ece0: 2e 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 49 66  ..** {F17303} If
ecf0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
ed00: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
ed10: 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
ed20: 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
ed30: 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
ed40: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 7b 46 31  LL pointer.  {F1
ed50: 37 33 30 34 7d 20 49 66 20 74 68 65 20 70 61 72  7304} If the par
ed60: 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
ed70: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
ed80: 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
ed90: 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
eda0: 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
edb0: 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
edc0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ter..**.** {F173
edd0: 30 35 7d 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69  05} Calling sqli
ede0: 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
edf0: 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
ee00: 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
ee10: 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
ee20: 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
ee30: 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
ee40: 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
ee50: 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
ee60: 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 7b  ht be reused.  {
ee70: 46 31 37 33 30 36 7d 20 54 68 65 20 73 71 6c 69  F17306} The sqli
ee80: 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
ee90: 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
eea0: 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
eeb0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
eec0: 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
eed0: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
eee0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
eef0: 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 7b 55  is harmless.  {U
ef00: 31 37 33 30 37 7d 20 41 66 74 65 72 20 62 65 69  17307} After bei
ef10: 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
ef20: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
ef30: 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
ef40: 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
ef50: 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
ef60: 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
ef70: 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
ef80: 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
ef90: 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
efa0: 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
efb0: 7b 55 31 37 33 30 39 7d 20 4d 65 6d 6f 72 79 20  {U17309} Memory 
efc0: 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
efd0: 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
efe0: 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
eff0: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
f000: 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
f010: 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
f020: 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
f030: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
f040: 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
f050: 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
f060: 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
f070: 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a  lite3_free()..**
f080: 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 54 68 65  .** {F17310} The
f090: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
f0a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
f0b0: 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
f0c0: 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
f0d0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
f0e0: 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
f0f0: 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
f100: 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
f110: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
f120: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f130: 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
f140: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
f150: 72 61 6d 65 74 65 72 2e 20 20 7b 46 31 37 33 31  rameter.  {F1731
f160: 31 7d 20 49 66 20 74 68 65 20 66 69 72 73 74 20  1} If the first 
f170: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
f180: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
f190: 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
f1a0: 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
f1b0: 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
f1c0: 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
f1d0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f1e0: 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
f1f0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
f200: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
f210: 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 7b 46 31 37  alloc()..** {F17
f220: 33 31 32 7d 20 49 66 20 74 68 65 20 73 65 63 6f  312} If the seco
f230: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
f240: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
f250: 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
f260: 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
f270: 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
f280: 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
f290: 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
f2a0: 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
f2b0: 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
f2c0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
f2d0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
f2e0: 2e 0a 2a 2a 20 7b 46 31 37 33 31 33 7d 20 53 71  ..** {F17313} Sq
f2f0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
f300: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
f310: 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
f320: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
f330: 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
f340: 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
f350: 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
f360: 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
f370: 62 6c 65 2e 0a 2a 2a 20 7b 46 31 37 33 31 34 7d  ble..** {F17314}
f380: 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
f390: 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
f3a0: 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
f3b0: 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
f3c0: 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
f3d0: 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
f3e0: 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
f3f0: 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
f400: 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
f410: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
f420: 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
f430: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
f440: 72 65 65 64 2e 0a 2a 2a 20 7b 46 31 37 33 31 35  reed..** {F17315
f450: 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61  } If sqlite3_rea
f460: 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
f470: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
f480: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
f490: 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
f4a0: 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 36 7d 20 54  **.** {F17316} T
f4b0: 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
f4c0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
f4d0: 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
f4e0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
f4f0: 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
f500: 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
f510: 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
f520: 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
f530: 31 37 33 38 31 7d 20 54 68 65 20 64 65 66 61 75  17381} The defau
f540: 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  lt implementatio
f550: 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f  n.** of the memo
f560: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
f570: 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 68 65  bsystem uses the
f580: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
f590: 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65  oc().** and free
f5a0: 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
f5b0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
f5c0: 62 72 61 72 79 2e 20 7b 46 31 37 33 38 32 7d 20  brary. {F17382} 
f5d0: 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20  However, if .** 
f5e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f5f0: 65 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c  ed with the foll
f600: 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65  owing C preproce
f610: 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a  ssor macro.**.**
f620: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51   <blockquote> SQ
f630: 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
f640: 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c  =<i>NNN</i> </bl
f650: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
f660: 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
f670: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   is an integer, 
f680: 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61  then SQLite crea
f690: 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61  te a static.** a
f6a0: 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74  rray of at least
f6b0: 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65   <i>NNN</i> byte
f6c0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73  s in size and us
f6d0: 65 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20  e that array.** 
f6e0: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
f6f0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
f700: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
f710: 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
f720: 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  l.** memory allo
f730: 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d 61  cator options ma
f740: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
f750: 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
f760: 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
f770: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
f780: 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
f790: 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
f7a0: 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
f7b0: 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
f7c0: 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
f7d0: 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
f7e0: 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
f7f0: 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
f800: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
f810: 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
f820: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
f830: 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
f840: 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
f850: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
f860: 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75  tors can be.** u
f870: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 77  sed..**.** The w
f880: 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
f890: 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
f8a0: 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
f8b0: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
f8c0: 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
f8d0: 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
f8e0: 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
f8f0: 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
f900: 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
f910: 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
f920: 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
f930: 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
f940: 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 77 69  he particular wi
f950: 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
f960: 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
f970: 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
f980: 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
f990: 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
f9a0: 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
f9b0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
f9c0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
f9d0: 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
f9e0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
f9f0: 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
fa00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
fa10: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
fa20: 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
fa30: 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
fa40: 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
fa50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
fa60: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
fa70: 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33  Statistics {F173
fa80: 37 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 64  70}.**.** In add
fa90: 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61 73  ition to the bas
faa0: 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61 74  ic three allocat
fab0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a  ion routines .**
fac0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
fad0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
fae0: 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
faf0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
fb00: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
fb10: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
fb20: 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  em included with
fb30: 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 73   the SQLite.** s
fb40: 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73 20  ources provides 
fb50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  the interfaces s
fb60: 68 6f 77 6e 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  hown here..**.**
fb70: 20 7b 46 31 37 33 37 31 7d 20 54 68 65 20 73 71   {F17371} The sq
fb80: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
fb90: 64 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  d() routine retu
fba0: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
fbb0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65  r of bytes of me
fbc0: 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
fbd0: 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
fbe0: 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
fbf0: 65 64 29 2e 0a 2a 2a 20 7b 46 31 37 33 37 32 7d  ed)..** {F17372}
fc00: 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
fc10: 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
fc20: 65 6d 6f 72 79 5f 75 73 65 64 28 29 20 69 6e 63  emory_used() inc
fc30: 6c 75 64 65 73 0a 2a 2a 20 61 6e 79 20 6f 76 65  ludes.** any ove
fc40: 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 53  rhead added by S
fc50: 51 4c 69 74 65 2c 20 62 75 74 20 6e 6f 74 20 6f  QLite, but not o
fc60: 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
fc70: 20 74 68 65 0a 2a 2a 20 6c 69 62 72 61 72 79 20   the.** library 
fc80: 6d 61 6c 6c 6f 63 28 29 20 74 68 61 74 20 62 61  malloc() that ba
fc90: 63 6b 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  cks the sqlite3_
fca0: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
fcb0: 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 37  ntation..** {F17
fcc0: 33 37 33 7d 20 54 68 65 20 73 71 6c 69 74 65 33  373} The sqlite3
fcd0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
fce0: 72 28 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  r() routines ret
fcf0: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6d 61 78 69  urns the.** maxi
fd00: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
fd10: 74 65 73 20 74 68 61 74 20 68 61 76 65 20 62 65  tes that have be
fd20: 65 6e 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61  en outstanding a
fd30: 74 20 61 6e 79 20 74 69 6d 65 0a 2a 2a 20 73 69  t any time.** si
fd40: 6e 63 65 20 74 68 65 20 68 69 67 68 77 61 74 65  nce the highwate
fd50: 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 73 74 20  r mark was last 
fd60: 72 65 73 65 74 2e 0a 2a 2a 20 7b 46 31 37 33 37  reset..** {F1737
fd70: 34 7d 20 54 68 65 20 62 79 74 65 20 63 6f 75 6e  4} The byte coun
fd80: 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
fd90: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
fda0: 68 77 61 74 65 72 28 29 0a 2a 2a 20 75 73 65 73  hwater().** uses
fdb0: 20 74 68 65 20 73 61 6d 65 20 62 79 74 65 20 63   the same byte c
fdc0: 6f 75 6e 74 69 6e 67 20 72 75 6c 65 73 20 61 73  ounting rules as
fdd0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
fde0: 75 73 65 64 28 29 2e 20 7b 45 4e 44 7d 0a 2a 2a  used(). {END}.**
fdf0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
fe00: 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
fe10: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
fe20: 4c 69 74 65 20 69 73 20 63 6f 75 6e 74 65 64 2c  Lite is counted,
fe30: 0a 2a 2a 20 62 75 74 20 6f 76 65 72 68 65 61 64  .** but overhead
fe40: 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c   from the underl
fe50: 79 69 6e 67 20 73 79 73 74 65 6d 20 6d 61 6c 6c  ying system mall
fe60: 6f 63 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 7b 46  oc is not..** {F
fe70: 31 37 33 37 35 7d 20 49 66 20 74 68 65 20 70 61  17375} If the pa
fe80: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
fe90: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
fea0: 74 65 72 28 29 20 69 73 20 74 72 75 65 2c 0a 2a  ter() is true,.*
feb0: 2a 20 74 68 65 6e 20 74 68 65 20 68 69 67 68 77  * then the highw
fec0: 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
fed0: 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
fee0: 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 73 71  t value of.** sq
fef0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
ff00: 64 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  d() and the prio
ff10: 72 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  r highwater mark
ff20: 20 28 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20   (before the.** 
ff30: 72 65 73 65 74 29 20 69 73 20 72 65 74 75 72 6e  reset) is return
ff40: 65 64 2e 20 20 7b 46 31 37 33 37 36 7d 20 20 49  ed.  {F17376}  I
ff50: 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
ff60: 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  to .** sqlite3_m
ff70: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
ff80: 29 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  ) is zero, then 
ff90: 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61  the highwater ma
ffa0: 72 6b 20 69 73 0a 2a 2a 20 75 6e 63 68 61 6e 67  rk is.** unchang
ffb0: 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  ed..*/.sqlite3_i
ffc0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
ffd0: 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
ffe0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
fff0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10000 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
10010 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
10020 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
10030 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
10040 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
10050 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2500}.**.** {F12
10060 35 30 31 7d 20 54 68 69 73 20 72 6f 75 74 69 6e  501} This routin
10070 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
10080 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
10090 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
100a0 6c 61 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  lar.** database 
100b0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 73 75 70 70  connection, supp
100c0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
100d0 74 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 32  t argument. {F12
100e0 35 30 32 7d 0a 2a 2a 20 54 68 65 20 61 75 74 68  502}.** The auth
100f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
10100 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
10110 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
10120 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
10130 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
10140 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
10150 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
10160 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
10170 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
10180 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
10190 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
101a0 36 5f 76 32 28 29 5d 2e 20 20 7b 46 31 32 35 30  6_v2()].  {F1250
101b0 33 7d 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a  3} At various.**
101c0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
101d0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
101e0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
101f0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
10200 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
10210 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
10220 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
10230 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
10240 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
10250 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
10260 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65  re allowed.  The
10270 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
10280 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
10290 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
102a0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
102b0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
102c0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
102d0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
102e0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
102f0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
10300 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
10310 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
10320 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
10330 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
10340 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
10350 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
10360 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
10370 65 72 72 6f 72 2e 20 20 7b 46 31 32 35 30 34 7d  error.  {F12504}
10380 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
10390 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
103a0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
103b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
103c0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
103d0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
103e0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
103f0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
10400 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
10410 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
10420 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
10430 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 73 68  he authorizer sh
10440 61 6c 6c 0a 2a 2a 20 66 61 69 6c 20 77 69 74 68  all.** fail with
10450 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   an SQLITE_ERROR
10460 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
10470 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
10480 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 7b 45  rror message. {E
10490 4e 44 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ND}.**.** When t
104a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
104b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
104c0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
104d0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
104e0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 7b  uested is ok.  {
104f0 46 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65  F12505} When the
10500 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
10510 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
10520 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
10530 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
10540 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
10550 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
10560 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
10570 65 72 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a  er shall fail.**
10580 20 77 69 74 68 20 61 6e 20 53 51 4c 49 54 45 5f   with an SQLITE_
10590 45 52 52 4f 52 20 65 72 72 6f 72 20 63 6f 64 65  ERROR error code
105a0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
105b0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
105c0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
105d0 69 73 20 64 65 6e 69 65 64 2e 20 7b 46 31 32 35  is denied. {F125
105e0 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  06} If the autho
105f0 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
10600 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
10610 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
10620 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
10630 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  nything other th
10640 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  an [SQLITE_READ]
10650 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 72 65 74 75  , then.** a retu
10660 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
10670 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
10680 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
10690 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 20  LITE_DENY]. .** 
106a0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
106b0 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  r code is [SQLIT
106c0 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20  E_READ] and the 
106d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
106e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
106f0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70 72 65  RE] then the pre
10700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
10710 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
10720 6f 0a 2a 2a 20 69 6e 73 65 72 74 20 61 20 4e 55  o.** insert a NU
10730 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
10740 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
10750 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
10760 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
10770 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
10780 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
10790 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ned. {END}.**.**
107a0 20 7b 46 31 32 35 31 30 7d 20 54 68 65 20 66 69   {F12510} The fi
107b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
107c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
107d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
107e0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69  py of.** the thi
107f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
10800 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
10810 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
10820 65 72 66 61 63 65 2e 0a 2a 2a 20 7b 46 31 32 35  erface..** {F125
10830 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  11} The second p
10840 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
10850 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
10860 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49  nteger .** [SQLI
10870 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
10880 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
10890 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63  ifies the partic
108a0 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74  ular action.** t
108b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
108c0 20 7b 45 4e 44 7d 20 54 68 65 20 61 76 61 69 6c   {END} The avail
108d0 61 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  able action code
108e0 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s are.** [SQLITE
108f0 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74  _COPY | document
10900 65 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20  ed separately]. 
10910 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20 74 68   {F12512} The th
10920 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
10930 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  h.** parameters 
10940 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
10950 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
10960 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
10970 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 64   contain .** add
10980 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
10990 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
109a0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
109b0 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 41  d. {END}.**.** A
109c0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
109d0 75 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72  used when prepar
109e0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
109f0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
10a00 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20  sted.** source, 
10a10 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
10a20 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
10a30 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  s do not try to 
10a40 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74  access data.** t
10a50 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74  hat they are not
10a60 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
10a70 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
10a80 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65   not try to.** e
10a90 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
10aa0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
10ab0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
10ac0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
10ad0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
10ae0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
10af0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
10b00 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
10b10 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
10b20 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
10b30 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
10b40 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
10b50 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
10b60 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
10b70 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
10b80 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
10b90 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
10ba0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
10bb0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
10bc0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
10bd0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
10be0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
10bf0 70 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69  prepared that di
10c00 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
10c10 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c  ng.** except SEL
10c20 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  ECT statements. 
10c30 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d   .**.** {F12520}
10c40 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   Only a single a
10c50 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
10c60 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
10c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10c80 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
10c90 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
10ca0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
10cb0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
10cc0 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
10cd0 63 61 6c 6c 2e 20 7b 46 31 32 35 32 31 7d 20 20  call. {F12521}  
10ce0 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65  A NULL authorize
10cf0 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  r means that no 
10d00 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
10d10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
10d20 6f 6b 65 64 2e 20 20 7b 46 31 32 35 32 32 7d 20  oked.  {F12522} 
10d30 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
10d40 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 20  orizer is NULL. 
10d50 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  {END}.**.** Note
10d60 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
10d70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
10d80 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
10d90 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ring .** [sqlite
10da0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
10db0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 7b  its variants.  {
10dc0 46 31 32 35 32 33 7d 20 41 75 74 68 6f 72 69 7a  F12523} Authoriz
10dd0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
10de0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
10df0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
10e00 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
10e10 33 5f 73 74 65 70 28 29 5d 2e 20 7b 45 4e 44 7d  3_step()]. {END}
10e20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10e30 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
10e40 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
10e50 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
10e60 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
10e70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
10e80 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
10e90 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
10ea0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
10eb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
10ec0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
10ed0 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a  odes {F12590}.**
10ee0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
10ef0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
10f00 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
10f10 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
10f20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
10f30 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
10f40 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
10f50 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
10f60 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
10f70 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
10f80 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
10f90 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
10fa0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
10fb0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
10fc0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
10fd0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
10fe0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
10ff0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
11000 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
11010 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
11020 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
11030 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
11040 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
11050 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
11060 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
11070 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
11080 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
11090 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
110a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
110b0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
110c0 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a  Codes {F12550}.*
110d0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
110e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
110f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
11100 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
11110 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
11120 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
11130 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72  o authorizer cer
11140 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
11150 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 7b 46 31  nt actions.  {F1
11160 32 35 35 31 7d 20 54 68 65 0a 2a 2a 20 73 65 63  2551} The.** sec
11170 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
11180 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
11190 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
111a0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
111b0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
111c0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
111d0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
111e0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
111f0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
11200 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
11210 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
11220 61 73 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  assed. {END}.**.
11230 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
11240 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
11250 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
11260 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
11270 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   be .** authoriz
11280 65 64 2e 20 20 7b 46 31 32 35 35 32 7d 20 54 68  ed.  {F12552} Th
11290 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
112a0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
112b0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
112c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
112d0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
112e0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
112f0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
11300 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
11310 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
11320 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11330 65 72 2e 20 7b 46 31 32 35 35 33 7d 20 54 68 65  er. {F12553} The
11340 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
11350 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
11360 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
11370 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
11380 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
11390 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74  , "temp", .** et
113a0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
113b0 65 2e 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20  e. {F12554} The 
113c0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
113d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
113e0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
113f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
11400 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
11410 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
11420 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
11430 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
11440 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
11450 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
11460 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
11470 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d  ly from .** top-
11480 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
11490 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
114a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
114b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
114c0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
114d0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
114e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
114f0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
11500 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
11510 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
11520 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
11530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11540 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
11550 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
11560 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
11570 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
11580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11590 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
115a0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
115b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
115c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
115d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
115e0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
115f0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
11600 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
11610 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
11620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
11630 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
11640 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
11650 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
11660 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
11670 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
11680 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
11690 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
116a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
116b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
116c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
116d0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
116e0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
116f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
11700 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
11710 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
11720 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
11730 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
11740 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
11750 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
11760 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
11770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
11780 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
11790 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
117a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
117b0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
117c0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
117d0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
117e0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
117f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
11800 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
11810 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
11820 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
11830 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
11840 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
11850 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
11860 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
11870 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
11880 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
11890 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
118a0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
118b0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
118c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
118d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
118e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
118f0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
11900 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
11910 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
11920 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
11930 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11940 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
11950 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
11960 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
11970 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
11980 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11990 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
119a0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
119b0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
119c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
119d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
119e0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
119f0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
11a00 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
11a10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
11a20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11a30 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
11a40 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
11a50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
11a60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
11a70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
11a80 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
11a90 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
11aa0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
11ab0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
11ac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
11ad0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
11ae0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
11af0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
11b00 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
11b10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
11b20 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
11b30 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
11b40 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
11b50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
11b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
11b70 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
11b80 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   22   /* NULL   
11b90 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
11ba0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
11bb0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
11bc0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
11bd0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
11be0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
11bf0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
11c00 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
11c10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
11c20 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
11c30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
11c40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
11c50 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
11c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
11c70 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
11c80 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
11c90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
11ca0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
11cb0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
11cc0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
11cd0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
11ce0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
11cf0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
11d00 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
11d10 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
11d20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
11d30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
11d40 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
11d50 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
11d60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
11d70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
11d80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
11d90 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
11da0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
11db0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
11dc0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
11dd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
11de0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
11df0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
11e00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
11e10 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
11e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11e30 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
11e40 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
11e50 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
11e60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
11e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11e80 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
11e90 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
11ea0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
11eb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11ec0 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
11ed0 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
11ee0 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a  s {F12280}.**.**
11ef0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
11f00 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
11f10 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
11f20 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
11f30 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
11f40 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
11f50 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
11f60 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
11f70 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63 61   {F12281} The ca
11f80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
11f90 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
11fa0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
11fb0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74   invoked.** at t
11fc0 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65  he first [sqlite
11fd0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68  3_step()] for th
11fe0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
11ff0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
12000 2e 0a 2a 2a 20 7b 46 31 32 32 38 32 7d 20 4f 6e  ..** {F12282} On
12010 6c 79 20 61 20 73 69 6e 67 6c 65 20 74 72 61 63  ly a single trac
12020 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62  e callback can b
12030 65 20 72 65 67 69 73 74 65 72 65 64 20 61 74 20  e registered at 
12040 61 20 74 69 6d 65 2e 0a 2a 2a 20 45 61 63 68 20  a time..** Each 
12050 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
12060 74 72 61 63 65 28 29 20 6f 76 65 72 72 69 64 65  trace() override
12070 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 2e 20  s the previous. 
12080 20 7b 46 31 32 32 38 33 7d 20 41 0a 2a 2a 20 4e   {F12283} A.** N
12090 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  ULL callback for
120a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
120b0 20 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e   disables tracin
120c0 67 2e 20 20 7b 46 31 32 32 38 34 7d 20 54 68 65  g.  {F12284} The
120d0 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
120e0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
120f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
12100 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
12110 72 20 77 68 69 63 68 0a 2a 2a 20 77 61 73 20 74  r which.** was t
12120 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
12130 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
12140 2e 20 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20  .  {F12285} The 
12150 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a  second argument.
12160 2a 2a 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  ** to the trace 
12170 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 7a 65  callback is a ze
12180 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
12190 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  F8 string contai
121a0 6e 69 6e 67 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ning.** the orig
121b0 69 6e 61 6c 20 74 65 78 74 20 6f 66 20 74 68 65  inal text of the
121c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
121d0 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20  s it was passed 
121e0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
121f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
12200 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
12210 2e 20 7b 45 4e 44 7d 20 20 4e 6f 74 65 20 74 68  . {END}  Note th
12220 61 74 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20 70  at the.** host p
12230 61 72 61 6d 65 74 65 72 20 61 72 65 20 6e 6f 74  arameter are not
12240 20 65 78 70 61 6e 64 65 64 20 69 6e 20 74 68 65   expanded in the
12250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
12260 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ext..**.** {F122
12270 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  87} The callback
12280 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
12290 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
122a0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
122b0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
122c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
122d0 6e 69 73 68 65 73 2e 20 20 7b 46 31 32 32 38 38  nishes.  {F12288
122e0 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
122f0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
12300 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
12310 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12320 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
12330 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  to sqlite3_profi
12340 6c 65 28 29 2e 0a 2a 2a 20 7b 46 31 32 32 38 39  le()..** {F12289
12350 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
12360 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
12370 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
12380 73 20 61 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d  s a.** zero-term
12390 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
123a0 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
123b0 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
123c0 65 78 74 20 6f 66 0a 2a 2a 20 74 68 65 20 53 51  ext of.** the SQ
123d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
123e0 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20  t was processed 
123f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
12400 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
12410 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 20  the equivalent. 
12420 20 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74 68   {F12290} The th
12430 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
12440 20 74 68 65 20 70 72 6f 66 69 6c 65 20 0a 2a 2a   the profile .**
12450 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
12460 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20  estimate of the 
12470 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
12480 63 6f 6e 64 73 20 6f 66 0a 2a 2a 20 77 61 6c 6c  conds of.** wall
12490 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75  -clock time requ
124a0 69 72 65 64 20 74 6f 20 72 75 6e 20 74 68 65 20  ired to run the 
124b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72  SQL statement fr
124c0 6f 6d 20 73 74 61 72 74 0a 2a 2a 20 74 6f 20 66  om start.** to f
124d0 69 6e 69 73 68 2e 20 7b 45 4e 44 7d 20 20 0a 2a  inish. {END}  .*
124e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
124f0 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69  _profile() API i
12500 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
12510 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
12520 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75  tal and.** is su
12530 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e  bject to change.
12540 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
12550 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
12560 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
12570 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
12580 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
12590 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
125a0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
125b0 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
125c0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
125d0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
125e0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
125f0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
12600 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
12610 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a  cks {F12910}.**.
12620 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 69 73  ** {F12911} This
12630 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
12640 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
12650 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
12660 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
12670 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
12680 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
12690 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
126a0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
126b0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
126c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
126d0 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
126e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
126f0 5d 2e 20 7b 45 4e 44 7d 20 20 41 6e 20 65 78 61  ]. {END}  An exa
12700 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
12710 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  s .** interface 
12720 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
12730 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
12740 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
12750 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68  *.** {F12912} Th
12760 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
12770 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
12780 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
12790 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
127a0 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72  ne opcodes, wher
127b0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
127c0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
127d0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  is function..** 
127e0 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f  {F12913} The pro
127f0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
12800 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
12810 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
12820 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
12830 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  this function. {
12840 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72  F12914} The four
12850 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
12860 68 69 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  his.** function 
12870 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74 65  is a void pointe
12880 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
12890 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
128a0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65 61  k.** function ea
128b0 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
128c0 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  voked. {END}.**.
128d0 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61  ** {F12915} If a
128e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
128f0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
12900 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a  te3_step()], or.
12910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
12920 74 61 62 6c 65 28 29 5d 20 72 65 73 75 6c 74 73  table()] results
12930 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e   in fewer than N
12940 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65   opcodes being e
12950 78 65 63 75 74 65 64 2c 0a 2a 2a 20 74 68 65 6e  xecuted,.** then
12960 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
12970 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20  llback is never 
12980 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a  invoked. {END}.*
12990 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20 4f  * .** {F12916} O
129a0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
129b0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66  gress callback f
129c0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
129d0 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61  egistered for ea
129e0 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ch.** open datab
129f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
12a00 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73   Every call to s
12a10 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
12a20 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65  handler().** ove
12a30 72 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75  rwrites the resu
12a40 6c 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69  lts of the previ
12a50 6f 75 73 20 63 61 6c 6c 2e 20 7b 46 31 32 39 31  ous call. {F1291
12a60 37 7d 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65 20  7}.** To remove 
12a70 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
12a80 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 68 65 72  lback altogether
12a90 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 73 20 74  , pass NULL as t
12aa0 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
12ab0 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
12ac0 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ction. {END}.**.
12ad0 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74  ** {F12918} If t
12ae0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
12af0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72  back returns a r
12b00 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e  esult other than
12b10 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   0, then.** the 
12b20 63 75 72 72 65 6e 74 20 71 75 65 72 79 20 69 73  current query is
12b30 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 74 65 72   immediately ter
12b40 6d 69 6e 61 74 65 64 20 61 6e 64 20 61 6e 79 20  minated and any 
12b50 64 61 74 61 62 61 73 65 20 63 68 61 6e 67 65 73  database changes
12b60 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  .** rolled back.
12b70 20 7b 46 31 32 39 31 39 7d 0a 2a 2a 20 54 68 65   {F12919}.** The
12b80 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71 6c   containing [sql
12b90 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
12ba0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
12bb0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  or.** [sqlite3_g
12bc0 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c 6c  et_table()] call
12bd0 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
12be0 49 4e 54 45 52 52 55 50 54 2e 20 7b 45 4e 44 7d  INTERRUPT. {END}
12bf0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 0a 2a    This feature.*
12c00 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 66  * can be used, f
12c10 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 69  or example, to i
12c20 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 22 43 61  mplement the "Ca
12c30 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
12c40 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 64 69  a.** progress di
12c50 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20 47 55  alog box in a GU
12c60 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  I..*/.void sqlit
12c70 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
12c80 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
12c90 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
12ca0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
12cb0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
12cc0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
12cd0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31  e Connection {F1
12ce0 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2700}.**.** {F12
12cf0 37 30 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69  701} These routi
12d00 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
12d10 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
12d20 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69   whose name.** i
12d30 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 66  s given by the f
12d40 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
12d50 2e 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68  ..** {F12702} Th
12d60 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
12d70 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
12d80 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66  ed as UTF-8.** f
12d90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
12da0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
12db0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20  _open_v2()] and 
12dc0 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20  as UTF-16.** in 
12dd0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
12de0 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74  order for [sqlit
12df0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
12e00 20 7b 46 31 32 37 30 33 7d 20 41 6e 20 5b 73 71   {F12703} An [sq
12e10 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69  lite3*] handle i
12e20 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  s returned in *p
12e30 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20  pDb, even.** if 
12e40 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
12e50 20 20 7b 46 31 32 37 32 33 7d 20 28 45 78 63 65    {F12723} (Exce
12e60 70 74 69 6f 6e 3a 20 69 66 20 53 51 4c 69 74 65  ption: if SQLite
12e70 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f   is unable.** to
12e80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
12e90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
12ea0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61  lite3] object, a
12eb0 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65   NULL will.** be
12ec0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
12ed0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
12ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
12ef0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
12f00 2e 29 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 49  .).** {F12704} I
12f10 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
12f20 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
12f30 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75 63   created).** suc
12f40 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 20  cessfully, then 
12f50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
12f60 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 32 37 30  eturned.  {F1270
12f70 35 7d 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a  5} Otherwise an.
12f80 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ** error code is
12f90 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 32   returned.  {F12
12fa0 37 30 36 7d 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  706} The.** [sql
12fb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
12fc0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
12fd0 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73  g16()]  routines
12fe0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
12ff0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
13000 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
13010 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
13020 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   error..**.** {F
13030 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75  12707} The defau
13040 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
13050 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
13060 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
13070 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
13080 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
13090 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c  en_v2()] is call
130a0 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
130b0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
130c0 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b 73 71  yte order if [sq
130d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
130e0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  is used..**.** {
130f0 46 31 32 37 30 38 7d 20 57 68 65 74 68 65 72 20  F12708} Whether 
13100 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
13110 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
13120 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
13130 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
13140 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
13150 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f  te3*] handle sho
13160 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
13170 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a 2a 2a  by passing it.**
13180 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
13190 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
131a0 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
131b0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  red..**.** {F127
131c0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
131d0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
131e0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
131f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
13200 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ] .** except tha
13210 74 20 69 74 20 61 63 63 63 65 70 74 73 20 74 77  t it acccepts tw
13220 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
13230 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
13240 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
13250 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
13260 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13270 6f 6e 2e 20 20 7b 46 31 32 37 31 30 7d 20 54 68  on.  {F12710} Th
13280 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
13290 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20  r can be.** one 
132a0 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  of:.**.** <ol>.*
132b0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
132c0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a  OPEN_READONLY].*
132d0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
132e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a  OPEN_READWRITE].
132f0 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
13300 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
13310 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
13320 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e  CREATE].** </ol>
13330 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20  .**.** {F12711} 
13340 54 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20  The first value 
13350 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
13360 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a  se read-only. .*
13370 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68  * {F12712} If th
13380 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
13390 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65  not previously e
133a0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
133b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 7b  s returned..** {
133c0 46 31 32 37 31 33 7d 20 54 68 65 20 73 65 63 6f  F12713} The seco
133d0 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a  nd option opens.
133e0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
133f0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
13400 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
13410 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20  ble, or reading 
13420 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68  only if.** if th
13430 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
13440 70 72 6f 74 65 63 74 65 64 2e 20 20 7b 46 31 32  protected.  {F12
13450 37 31 34 7d 20 49 6e 20 65 69 74 68 65 72 20 63  714} In either c
13460 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
13470 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61 64 79  .** must already
13480 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72   exist or an err
13490 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  or is returned. 
134a0 20 7b 46 31 32 37 31 35 7d 20 54 68 65 20 74 68   {F12715} The th
134b0 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70  ird option.** op
134c0 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ens the database
134d0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
134e0 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65   writing and cre
134f0 61 74 65 73 20 69 74 20 69 66 20 69 74 20 64 6f  ates it if it do
13500 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64  es.** not alread
13510 79 20 65 78 69 73 74 2e 20 7b 46 31 32 37 31 36  y exist. {F12716
13520 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 6f  }.** The third o
13530 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61 76 69  ptions is behavi
13540 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
13550 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71 6c 69  s used for [sqli
13560 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61  te3_open()].** a
13570 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
13580 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  16()]..**.** {F1
13590 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c  2717} If the fil
135a0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
135b0 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69  y:", then an pri
135c0 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72  vate.** in-memor
135d0 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
135e0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
135f0 6e 6e 65 63 74 69 6f 6e 2e 20 7b 46 31 32 37 31  nnection. {F1271
13600 38 7d 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72  8} This in-memor
13610 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 69  y.** database wi
13620 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 20 74  ll vanish when t
13630 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
13640 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
13650 2e 20 7b 45 4e 44 7d 20 20 46 75 74 75 72 65 0a  . {END}  Future.
13660 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
13670 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b 65 20  Lite might make 
13680 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
13690 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
136a0 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65 67 69  mes.** that begi
136b0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
136c0 68 61 72 61 63 74 65 72 2e 20 20 49 74 20 69 73  haracter.  It is
136d0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
136e0 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61 74  t .** when a dat
136f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 72  abase filename r
13700 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  eally does begin
13710 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61   with.** ":" tha
13720 74 20 79 6f 75 20 70 72 65 66 69 78 20 74 68 65  t you prefix the
13730 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
13740 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22   pathname like "
13750 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20  ./" to.** avoid 
13760 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
13770 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68 65   {F12719} If the
13780 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
13790 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
137a0 65 6e 20 61 20 70 72 69 76 61 74 65 20 74 65 6d  en a private tem
137b0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
137c0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
137d0 62 65 20 63 72 65 61 74 65 64 2e 20 20 7b 46 31  be created.  {F1
137e0 32 37 32 30 7d 20 54 68 69 73 20 70 72 69 76 61  2720} This priva
137f0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
13800 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
13810 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
13820 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
13830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
13840 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
13850 20 7b 46 31 32 37 32 31 7d 20 54 68 65 20 66 6f   {F12721} The fo
13860 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
13870 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
13880 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
13890 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
138a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
138b0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
138c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
138d0 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74   .** interface t
138e0 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74 61  hat the new data
138f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
13900 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 7b 46 31  should use.  {F1
13910 32 37 32 32 7d 20 49 66 20 74 68 65 0a 2a 2a 20  2722} If the.** 
13920 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
13930 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
13940 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
13950 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
13960 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75  ].** object is u
13970 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  sed. {END}.**.**
13980 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e 64   <b>Note to wind
13990 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
139a0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
139b0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
139c0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
139d0 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
139e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
139f0 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20  open_v2()] must 
13a00 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
13a10 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
13a20 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
13a30 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
13a40 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
13a50 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
13a60 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
13a70 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
13a80 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
13a90 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
13aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
13ab0 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
13ac0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  _open_v2()]..*/.
13ad0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
13ae0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
13af0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
13b00 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
13b10 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
13b20 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
13b30 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
13b40 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
13b50 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
13b60 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
13b70 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
13b80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
13b90 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
13ba0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
13bb0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
13bc0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
13bd0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
13be0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
13bf0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
13c00 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
13c10 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
13c20 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
13c30 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
13c40 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
13c50 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
13c60 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
13c70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
13c80 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
13c90 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
13ca0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
13cb0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
13cc0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
13cd0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
13ce0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
13cf0 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12800}.**.** {F
13d00 31 32 38 30 31 7d 20 54 68 65 20 73 71 6c 69 74  12801} The sqlit
13d10 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
13d20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
13d30 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53  he numeric.** [S
13d40 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
13d50 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49  t code] or [SQLI
13d60 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
13d70 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
13d80 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  code].** for the
13d90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
13da0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
13db0 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
13dc0 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74  d.** with [sqlit
13dd0 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e  e3] handle 'db'.
13de0 20 7b 55 31 32 38 30 32 7d 20 49 66 20 61 20 70   {U12802} If a p
13df0 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
13e00 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20  iled but the.** 
13e10 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
13e20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
13e30 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
13e40 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
13e50 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e  rcode().** is un
13e60 64 65 66 69 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a  defined. {END}.*
13e70 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54 68  *.** {F12803} Th
13e80 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
13e90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
13ea0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
13eb0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
13ec0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
13ed0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
13ee0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
13ef0 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
13f00 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 7b 46 31  ectively..** {F1
13f10 32 38 30 34 7d 20 4d 65 6d 6f 72 79 20 74 6f 20  2804} Memory to 
13f20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
13f30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
13f40 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
13f50 6c 6c 79 2e 0a 2a 2a 20 7b 55 31 32 38 30 35 7d  lly..** {U12805}
13f60 20 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20   The .** string 
13f70 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69 74 74  may be overwritt
13f80 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
13f90 64 20 62 79 20 73 75 62 73 65 71 75 65 6e 74 20  d by subsequent 
13fa0 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a  calls to SQLite.
13fb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  ** interface fun
13fc0 63 74 69 6f 6e 73 2e 20 7b 45 4e 44 7d 0a 2a 2a  ctions. {END}.**
13fd0 0a 2a 2a 20 7b 46 31 32 38 30 36 7d 20 43 61 6c  .** {F12806} Cal
13fe0 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74  ls to many sqlit
13ff0 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73  e3_* functions s
14000 65 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  et the error cod
14010 65 20 61 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 20  e and.** string 
14020 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
14030 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
14040 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
14050 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
14060 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
14070 20 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68 65   overwriting the
14080 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73   previous values
14090 2e 20 20 7b 46 31 32 38 30 37 7d 0a 2a 2a 20 45  .  {F12807}.** E
140a0 78 63 65 70 74 2c 20 63 61 6c 6c 73 20 74 6f 20  xcept, calls to 
140b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
140c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
140d0 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20  _errmsg()], and 
140e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
140f0 36 28 29 5d 20 74 68 65 6d 73 65 6c 76 65 73 20  6()] themselves 
14100 64 6f 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  do not affect th
14110 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20 6f 66 20  e.** results of 
14120 66 75 74 75 72 65 20 69 6e 76 6f 63 61 74 69 6f  future invocatio
14130 6e 73 2e 20 20 7b 46 31 32 38 30 38 7d 20 43 61  ns.  {F12808} Ca
14140 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69  lls to API routi
14150 6e 65 73 20 74 68 61 74 0a 2a 2a 20 64 6f 20 6e  nes that.** do n
14160 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ot return an err
14170 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65  or code (example
14180 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
14190 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74  count()]) do not
141a0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 65  .** change the e
141b0 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e  rror code return
141c0 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
141d0 6e 65 2e 20 20 7b 46 31 32 38 30 39 7d 20 49 6e  ne.  {F12809} In
141e0 74 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a 2a  terfaces that.**
141f0 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61   are not associa
14200 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69  ted with a speci
14210 66 69 63 20 64 61 74 61 62 61 73 65 20 63 6f 6e  fic database con
14220 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d 70 6c 65  nection (example
14230 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  s:.** [sqlite3_m
14240 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
14250 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
14260 72 65 64 5f 63 61 63 68 65 28 29 5d 20 64 6f 20  red_cache()] do 
14270 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  not change.** th
14280 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 20 7b  e return code. {
14290 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  END}.**.** {F128
142a0 31 30 7d 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20  10} Assuming no 
142b0 6f 74 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e  other intervenin
142c0 67 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  g sqlite3_* API 
142d0 63 61 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 0a  calls are made,.
142e0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
142f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
14300 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
14310 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
14320 68 65 20 73 61 6d 65 0a 2a 2a 20 65 72 72 6f 72  he same.** error
14330 20 61 73 20 74 68 65 20 73 74 72 69 6e 67 73 20   as the strings 
14340 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
14350 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
14360 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
14370 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sg16()]..*/.int 
14380 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
14390 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
143a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
143b0 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
143c0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
143d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
143e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
143f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
14400 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
14410 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13000}.**.**
14420 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
14430 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
14440 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c  esent single SQL
14450 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
14460 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20  is.** object is 
14470 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
14480 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
14490 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a  tatement" or a .
144a0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
144b0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
144c0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
144d0 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54  ement"..** .** T
144e0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
144f0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
14500 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
14510 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
14520 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
14530 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
14540 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
14550 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
14560 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
14570 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
14580 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
14590 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
145a0 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73  using.**      [s
145b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
145c0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
145d0 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a  * interfaces]..*
145e0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
145f0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
14600 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
14610 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
14620 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
14630 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
14640 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
14650 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
14660 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
14670 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
14680 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
14690 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
146a0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
146b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
146c0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
146d0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
146e0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
146f0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
14700 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
14710 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
14720 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
14730 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
14740 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
14750 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
14760 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
14770 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
14780 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a  ent {F13010}.**.
14790 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
147a0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
147b0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
147c0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
147d0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
147e0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
147f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a  hese routines. .
14800 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54  **.** {F13011} T
14810 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14820 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 71  t "db" is an [sq
14830 6c 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 64  lite3 | SQLite d
14840 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20  atabase handle] 
14850 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
14860 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  m a prior call t
14870 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
14880 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
14890 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  n_v2()].** or [s
148a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
148b0 2e 20 7b 46 31 33 30 31 32 7d 0a 2a 2a 20 54 68  . {F13012}.** Th
148c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
148d0 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20  t "zSql" is the 
148e0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
148f0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
14900 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
14910 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
14920 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
14930 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
14940 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
14950 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
14960 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c  es UTF-8 and sql
14970 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
14980 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
14990 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
149a0 73 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d  se UTF-16. {END}
149b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d 20  .**.** {F13013} 
149c0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
149d0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a 2a  ument is less.**
149e0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
149f0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
14a00 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
14a10 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
14a20 2a 20 7b 46 31 33 30 31 34 7d 20 49 66 20 6e 42  * {F13014} If nB
14a30 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
14a40 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
14a50 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
14a60 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20  er of .** bytes 
14a70 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
14a80 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e   When nByte is n
14a90 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
14aa0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
14ab0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
14ac0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
14ad0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
14ae0 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74  acter or .** unt
14af0 69 6c 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  il the nByte-th 
14b00 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
14b10 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b 45 4e  comes first. {EN
14b20 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 35  D}.**.** {F13015
14b30 7d 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  } *pzTail is mad
14b40 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
14b50 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73  e first byte pas
14b60 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
14b70 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74  .** first SQL st
14b80 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
14b90 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
14ba0 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20 74   only compiles t
14bb0 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74  he first.** stat
14bc0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
14bd0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
14be0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68  t pointing to wh
14bf0 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e  at remains.** un
14c00 63 6f 6d 70 69 6c 65 64 2e 20 7b 45 4e 44 7d 0a  compiled. {END}.
14c10 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 2a  **.** {F13016} *
14c20 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
14c30 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
14c40 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  piled .** [sqlit
14c50 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74  e3_stmt | SQL st
14c60 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74 75 72  atement structur
14c70 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  e] that can be.*
14c80 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
14c90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
14ca0 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20  ].  Or if there 
14cb0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
14cc0 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73  Stmt may be.** s
14cd0 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 7b 46 31  et to NULL.  {F1
14ce0 33 30 31 37 7d 20 49 66 20 74 68 65 20 69 6e 70  3017} If the inp
14cf0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
14d00 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
14d10 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20  input.** is and 
14d20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
14d30 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
14d40 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
14d50 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30  o NULL..** {U130
14d60 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  18} The calling 
14d70 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
14d80 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
14d90 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d  eting the.** com
14da0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
14db0 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ent.** using [sq
14dc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
14dd0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
14de0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
14df0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d 20  .**.** {F13019} 
14e00 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
14e10 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
14e20 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
14e30 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  an .** [SQLITE_E
14e40 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64  RROR | error cod
14e50 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  e] is returned. 
14e60 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
14e70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14e80 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
14e90 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
14ea0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
14eb0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
14ec0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
14ed0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
14ee0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
14ef0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
14f00 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14f10 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
14f20 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
14f30 75 72 61 67 65 64 2e 0a 2a 2a 20 7b 46 31 33 30  uraged..** {F130
14f40 32 30 7d 20 49 6e 20 74 68 65 20 22 76 32 22 20  20} In the "v2" 
14f50 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
14f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14f70 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
14f80 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
14f90 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
14fa0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
14fb0 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72  py of the .** or
14fc0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
14fd0 20 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73   {END} This caus
14fe0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
14ff0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
15000 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61  e to.** behave a
15010 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
15020 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  two ways:.**.** 
15030 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 7b 46 31 33  <ol>.** <li>{F13
15040 30 32 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20 64  022}.** If the d
15050 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
15060 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
15070 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
15080 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
15090 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
150a0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
150b0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
150c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
150d0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
150e0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
150f0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
15100 61 69 6e 2e 20 7b 46 31 32 30 32 33 7d 20 49 66  ain. {F12023} If
15110 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20   the schema has 
15120 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20  changed in.** a 
15130 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74  way that makes t
15140 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20  he statement no 
15150 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73  longer valid, [s
15160 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
15170 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74  ill still.** ret
15180 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  urn [SQLITE_SCHE
15190 4d 41 5d 2e 20 20 7b 45 4e 44 7d 20 42 75 74 20  MA].  {END} But 
151a0 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
151b0 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20  y behavior, .** 
151c0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
151d0 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  is now a fatal e
151e0 72 72 6f 72 2e 20 20 7b 46 31 32 30 32 34 7d 20  rror.  {F12024} 
151f0 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  Calling.** [sqli
15200 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
15210 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74  ] again will not
15220 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72   make the.** err
15230 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 7b 46 31  or go away.  {F1
15240 32 30 32 35 7d 20 4e 6f 74 65 3a 20 75 73 65 20  2025} Note: use 
15250 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
15260 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
15270 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
15280 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
15290 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
152a0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
152b0 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  eturn. {END}.** 
152c0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
152d0 0a 2a 2a 20 7b 46 31 33 30 33 30 7d 20 57 68 65  .** {F13030} Whe
152e0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
152f0 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s, .** [sqlite3_
15300 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
15310 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
15320 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c  etailed .** [SQL
15330 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75  ITE_ERROR | resu
15340 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
15350 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
15360 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
15370 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 7b 46  sult codes].  {F
15380 31 33 30 33 31 7d 0a 2a 2a 20 54 68 65 20 6c 65  13031}.** The le
15390 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
153a0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
153b0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
153c0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
153d0 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ric.** [SQLITE_E
153e0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
153f0 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  e and you would 
15400 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
15410 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a  econd call to.**
15420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
15430 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
15440 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
15450 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
15460 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 7b 46 31 33  problem..** {F13
15470 30 33 32 7d 0a 2a 2a 20 57 69 74 68 20 74 68 65  032}.** With the
15480 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e   "v2" prepare in
15490 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
154a0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
154b0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
154c0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d  .** returned imm
154d0 65 64 69 61 74 65 6c 79 2e 20 7b 45 4e 44 7d 0a  ediately. {END}.
154e0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
154f0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
15500 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
15510 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
15520 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
15530 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
15540 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
15550 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
15560 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
15570 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
15580 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
15590 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
155a0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
155b0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
155c0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
155d0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
155e0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
155f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
15600 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
15610 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
15620 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
15630 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
15640 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
15650 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
15660 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
15670 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
15680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
15690 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
156a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
156b0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
156c0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
156d0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
156e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
156f0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
15700 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
15710 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
15720 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
15730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
15740 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
15750 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
15760 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
15770 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
15780 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
15790 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
157a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
157b0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
157c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
157d0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
157e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
157f0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
15800 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
15810 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
15820 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
15830 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
15840 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
15850 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
15860 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
15870 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
15880 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
15890 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
158a0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
158b0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
158c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
158d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
158e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
158f0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
15900 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
15910 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
15920 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
15930 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
15940 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
15950 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
15960 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
15970 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
15980 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
15990 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
159a0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
159b0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
159c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
159d0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
159e0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
159f0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
15a00 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
15a10 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74  .** CAPIREF: Ret
15a20 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
15a30 74 20 53 51 4c 20 7b 46 31 33 31 30 30 7d 0a 2a  t SQL {F13100}.*
15a40 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d 20 49 66  *.** {F13101} If
15a50 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51   the compiled SQ
15a60 4c 20 73 74 61 74 65 6d 65 6e 74 20 70 61 73 73  L statement pass
15a70 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d 65 6e  ed as an argumen
15a80 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
15a90 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
15aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
15ab0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
15ac0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
15ad0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  ],.** then this 
15ae0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
15af0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15b00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
15b10 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 74 61 69  string.** contai
15b20 6e 69 6e 67 20 61 20 63 6f 70 79 20 6f 66 20 74  ning a copy of t
15b30 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  he original SQL 
15b40 73 74 61 74 65 6d 65 6e 74 2e 20 7b 46 31 33 31  statement. {F131
15b50 30 32 7d 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  02} The.** point
15b60 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
15b70 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 0a  l the statement.
15b80 2a 2a 20 69 73 20 64 65 6c 65 74 65 64 20 75 73  ** is deleted us
15b90 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
15ba0 6c 69 7a 65 28 29 2e 0a 2a 2a 20 7b 46 31 33 31  lize()..** {F131
15bb0 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72  03} The string r
15bc0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
15bd0 65 33 5f 73 71 6c 28 29 20 69 73 20 61 6c 77 61  e3_sql() is alwa
15be0 79 73 20 55 54 46 38 20 65 76 65 6e 0a 2a 2a 20  ys UTF8 even.** 
15bf0 69 66 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  if a UTF16 strin
15c00 67 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79  g was originally
15c10 20 65 6e 74 65 72 65 64 20 75 73 69 6e 67 20 5b   entered using [
15c20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
15c30 36 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  6_v2()].** or th
15c40 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a  e equivalent..**
15c50 0a 2a 2a 20 7b 46 31 33 31 30 34 7d 20 49 66 20  .** {F13104} If 
15c60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
15c70 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  s compiled using
15c80 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 20 6c   either of the l
15c90 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
15ca0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
15cb0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
15cc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
15cd0 2c 20 74 68 69 73 0a 2a 2a 20 66 75 6e 63 74 69  , this.** functi
15ce0 6f 6e 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  on returns NULL.
15cf0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
15d00 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
15d10 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
15d20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15d30 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  F:  Dynamically 
15d40 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
15d50 63 74 20 20 7b 46 31 35 30 30 30 7d 0a 2a 2a 0a  ct  {F15000}.**.
15d60 2a 2a 20 7b 46 31 35 30 30 31 7d 20 53 51 4c 69  ** {F15001} SQLi
15d70 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
15d80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
15d90 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
15da0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
15db0 20 61 72 65 20 6f 72 20 63 61 6e 20 62 65 20 73   are or can be s
15dc0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
15dd0 61 73 65 20 74 61 62 6c 65 2e 20 7b 45 4e 44 7d  ase table. {END}
15de0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
15df0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66  dynamic typing f
15e00 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
15e10 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a 20 7b 46   stores.  .** {F
15e20 31 35 30 30 32 7d 20 56 61 6c 75 65 73 20 73 74  15002} Values st
15e30 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
15e40 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61  value objects ca
15e50 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67  n be.** be integ
15e60 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
15e70 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
15e80 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
15e90 55 4c 4c 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ULL..*/.typedef 
15ea0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
15eb0 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
15ec0 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20   CAPI3REF:  SQL 
15ed0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
15ee0 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d   Object {F16001}
15ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
15f00 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
15f10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
15f20 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
15f30 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
15f40 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
15f50 20 7b 46 31 36 30 30 32 7d 20 41 20 70 6f 69 6e   {F16002} A poin
15f60 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
15f70 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62 6a  3_context.** obj
15f80 65 63 74 20 69 73 20 61 6c 77 61 79 73 20 66 69  ect is always fi
15f90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
15fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
15fb0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
15fc0 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ns..*/.typedef s
15fd0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
15fe0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
15ff0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
16000 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67  PI3REF:  Binding
16010 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
16020 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
16030 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F13500}.**.** {F
16040 31 33 35 30 31 7d 20 49 6e 20 74 68 65 20 53 51  13501} In the SQ
16050 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20  L strings input 
16060 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
16070 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
16080 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20 6c  s.** variants, l
16090 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
160a0 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72 61  eplace by a para
160b0 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20  meter in one.** 
160c0 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a  of these forms:.
160d0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
160e0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
160f0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41 41  NNN.** <li>  :AA
16100 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41 0a  A.** <li>  @AAA.
16110 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
16120 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
16130 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f  the parameter fo
16140 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  rms shown above 
16150 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
16160 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41 41  r literal,.** AA
16170 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  A is an alphanum
16180 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 20  eric identifier 
16190 61 6e 64 20 56 56 56 20 69 73 20 61 20 76 61 72  and VVV is a var
161a0 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f 72  iable name accor
161b0 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ding.** to the s
161c0 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20 74  yntax rules of t
161d0 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d 69  he TCL programmi
161e0 6e 67 20 6c 61 6e 67 75 61 67 65 2e 20 7b 45 4e  ng language. {EN
161f0 44 7d 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  D}.** The values
16200 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
16210 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
16220 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
16230 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e  r names").** can
16240 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
16250 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
16260 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
16270 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
16280 7b 46 31 33 35 30 32 7d 20 54 68 65 20 66 69 72  {F13502} The fir
16290 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
162a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
162b0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c 77  *() routines alw
162c0 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ays.** is a poin
162d0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
162e0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
162f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
16300 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
16310 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
16320 76 61 72 69 61 6e 74 73 2e 20 20 7b 46 31 33 35  variants.  {F135
16330 30 33 7d 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a  03} The second.*
16340 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  * argument is th
16350 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70  e index of the p
16360 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
16370 65 74 2e 20 20 7b 46 31 33 35 30 34 7d 20 54 68  et.  {F13504} Th
16380 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
16390 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
163a0 78 20 6f 66 20 31 2e 20 20 7b 46 31 33 35 30 35  x of 1.  {F13505
163b0 7d 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20  } When the same 
163c0 6e 61 6d 65 64 0a 2a 2a 20 70 61 72 61 6d 65 74  named.** paramet
163d0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
163e0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
163f0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
16400 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
16410 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
16420 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
16430 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 0a 2a 2a   occurrence. .**
16440 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20 69 6e   {F13506} The in
16450 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
16460 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
16470 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
16480 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
16490 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
164a0 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65  ame()] API if de
164b0 73 69 72 65 64 2e 20 20 7b 46 31 33 35 30 37 7d  sired.  {F13507}
164c0 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
164d0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
164e0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
164f0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 7b 46 31 33   of NNN..** {F13
16500 35 30 38 7d 20 54 68 65 20 4e 4e 4e 20 76 61 6c  508} The NNN val
16510 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
16520 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d  en 1 and the com
16530 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72  pile-time.** par
16540 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41  ameter SQLITE_MA
16550 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  X_VARIABLE_NUMBE
16560 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  R (default value
16570 3a 20 39 39 39 29 2e 20 7b 45 4e 44 7d 0a 2a 2a  : 999). {END}.**
16580 20 53 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69   See <a href="li
16590 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74  mits.html">limit
165a0 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61  s.html</a> for a
165b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
165c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ation..**.** {F1
165d0 33 35 30 39 7d 20 54 68 65 20 74 68 69 72 64 20  3509} The third 
165e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
165f0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
16600 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
16610 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  {END}.**.** {F13
16620 35 31 30 7d 20 49 6e 20 74 68 6f 73 65 0a 2a 2a  510} In those.**
16630 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
16640 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
16650 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
16660 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16670 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68  f bytes.** in th
16680 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
16690 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
166a0 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62  alue is the numb
166b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
166c0 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f  he.** string, no
166d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
166e0 63 68 61 72 61 63 74 65 72 73 2e 20 7b 46 31 33  characters. {F13
166f0 35 31 31 7d 20 20 54 68 65 20 6e 75 6d 62 65 72  511}  The number
16700 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64 6f 65  .** of bytes doe
16710 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  s not include th
16720 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
16730 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20  r at the end of 
16740 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 7b 46 31 33  strings..** {F13
16750 35 31 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20 66  512}.** If the f
16760 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
16770 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
16780 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
16790 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d 62  tring is.** numb
167a0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
167b0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
167c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 7b 45 4e   terminator. {EN
167d0 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 33  D}.**.** {F13513
167e0 7d 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  }.** The fifth a
167f0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
16800 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
16810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
16820 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
16830 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
16840 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
16850 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
16860 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
16870 0a 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53  .** text after S
16880 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
16890 65 64 20 77 69 74 68 20 69 74 2e 20 7b 46 31 33  ed with it. {F13
168a0 35 31 34 7d 20 49 66 20 74 68 65 20 66 69 66 74  514} If the fift
168b0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
168c0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
168d0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
168e0 43 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62  C], then the lib
168f0 72 61 72 79 20 61 73 73 75 6d 65 73 20 74 68 61  rary assumes tha
16900 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
16910 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
16920 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
16930 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
16940 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
16950 2e 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20 49 66  ..** {F13515} If
16960 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
16970 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
16980 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
16990 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
169a0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
169b0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
169c0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
169d0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
169e0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
169f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
16a00 72 65 74 75 72 6e 73 2e 20 7b 45 4e 44 7d 0a 2a  returns. {END}.*
16a10 2a 0a 2a 2a 20 7b 46 31 33 35 32 30 7d 20 54 68  *.** {F13520} Th
16a20 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
16a30 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
16a40 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
16a50 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
16a60 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
16a70 68 20 7a 65 72 6f 73 2e 20 20 7b 46 31 33 35 32  h zeros.  {F1352
16a80 31 7d 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73  1} A zeroblob us
16a90 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
16aa0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
16ab0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
16ac0 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29  to hold it size)
16ad0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
16ae0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 20 7b 45  ng processed. {E
16af0 4e 44 7d 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ND}.** Zeroblobs
16b00 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
16b10 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d   serve as place-
16b20 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
16b30 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
16b40 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
16b50 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ten using .** [s
16b60 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
16b70 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f   | increment BLO
16b80 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
16b90 20 7b 46 31 33 35 32 32 7d 20 41 20 6e 65 67 61   {F13522} A nega
16ba0 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f  tive.** value fo
16bb0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
16bc0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
16bd0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 20 7b 45  -length BLOB. {E
16be0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33  ND}.**.** {F1353
16bf0 30 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  0} The sqlite3_b
16c00 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
16c10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
16c20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
16c30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16c40 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
16c50 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
16c60 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
16c70 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
16c80 74 65 70 28 29 5d 2e 20 7b 46 31 33 35 33 31 7d  tep()]. {F13531}
16c90 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
16ca0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
16cb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
16cc0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
16cd0 2a 20 7b 46 31 33 35 33 32 7d 20 55 6e 62 6f 75  * {F13532} Unbou
16ce0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
16cf0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16d00 20 4e 55 4c 4c 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a   NULL. {END}.**.
16d10 2a 2a 20 7b 46 31 33 35 34 30 7d 20 54 68 65 73  ** {F13540} Thes
16d20 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
16d30 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
16d40 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65   success or an e
16d50 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20  rror code if.** 
16d60 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
16d70 6f 6e 67 2e 20 20 7b 46 31 33 35 34 31 7d 20 5b  ong.  {F13541} [
16d80 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
16d90 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
16da0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
16db0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
16dc0 6e 67 65 2e 20 20 7b 46 31 33 35 34 32 7d 20 5b  nge.  {F13542} [
16dd0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
16de0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
16df0 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 7b 46  loc fails..** {F
16e00 31 33 35 34 33 7d 20 5b 53 51 4c 49 54 45 5f 4d  13543} [SQLITE_M
16e10 49 53 55 53 45 5d 20 69 73 20 72 65 74 75 72 6e  ISUSE] is return
16e20 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
16e30 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
16e40 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
16e50 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
16e60 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
16e70 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
16e80 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
16e90 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  zed..*/.int sqli
16ea0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
16eb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
16ec0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
16ed0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
16ee0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
16ef0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
16f00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
16f10 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
16f20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
16f30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
16f40 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
16f50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
16f60 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
16f70 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
16f80 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
16f90 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
16fa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
16fb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
16fc0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
16fd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
16fe0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
16ff0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
17000 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
17010 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
17020 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
17030 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
17040 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
17050 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
17060 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
17070 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
17080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
17090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
170a0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
170b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
170c0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
170d0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
170e0 66 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  f Host Parameter
170f0 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a  s {F13600}.**.**
17100 20 7b 46 31 33 36 30 31 7d 20 52 65 74 75 72 6e   {F13601} Return
17110 20 74 68 65 20 6c 61 72 67 65 73 74 20 68 6f 73   the largest hos
17120 74 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 65  t parameter inde
17130 78 20 69 6e 20 74 68 65 20 70 72 65 63 6f 6d 70  x in the precomp
17140 69 6c 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  iled.** statemen
17150 74 20 67 69 76 65 6e 20 61 73 20 74 68 65 20 61  t given as the a
17160 72 67 75 6d 65 6e 74 2e 20 7b 46 31 33 36 30 32  rgument. {F13602
17170 7d 20 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20  } When the host 
17180 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 61 72  parameters.** ar
17190 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 6c  e of the forms l
171a0 69 6b 65 20 22 3a 41 41 41 22 2c 20 22 24 56 56  ike ":AAA", "$VV
171b0 56 22 2c 20 22 40 41 41 41 22 2c 20 6f 72 20 22  V", "@AAA", or "
171c0 3f 22 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 79  ?",.** then they
171d0 20 61 72 65 20 61 73 73 69 67 6e 65 64 20 73 65   are assigned se
171e0 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 65 61 73  quential increas
171f0 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 65 67 69  ing numbers begi
17200 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 6e  nning.** with on
17210 65 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20  e, so the value 
17220 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
17230 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
17240 74 65 72 73 2e 0a 2a 2a 20 7b 46 31 33 36 30 33  ters..** {F13603
17250 7d 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20  } However.** if 
17260 74 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61  the same host pa
17270 72 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20  rameter name is 
17280 75 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  used multiple ti
17290 6d 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72  mes, each occurr
172a0 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e  ance.** is given
172b0 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
172c0 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72  , so the value r
172d0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20  eturned in that 
172e0 63 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62  case is the numb
172f0 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20  er.** of unique 
17300 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
17310 61 6d 65 73 2e 20 7b 46 31 33 36 30 34 7d 20 49  ames. {F13604} I
17320 66 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  f host parameter
17330 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
17340 20 22 3f 4e 4e 4e 22 20 61 72 65 20 75 73 65 64   "?NNN" are used
17350 20 28 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61   (where NNN is a
17360 6e 20 69 6e 74 65 67 65 72 29 20 74 68 65 6e 20  n integer) then 
17370 74 68 65 72 65 20 6d 69 67 68 74 20 62 65 0a 2a  there might be.*
17380 2a 20 67 61 70 73 20 69 6e 20 74 68 65 20 6e 75  * gaps in the nu
17390 6d 62 65 72 69 6e 67 20 61 6e 64 20 74 68 65 20  mbering and the 
173a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
173b0 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
173c0 20 69 73 0a 2a 2a 20 74 68 65 20 69 6e 64 65 78   is.** the index
173d0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 70 61 72   of the host par
173e0 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20  ameter with the 
173f0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 76 61  largest index va
17400 6c 75 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  lue. {END}.**.**
17410 20 7b 55 31 33 36 30 35 7d 20 54 68 65 20 70 72   {U13605} The pr
17420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
17430 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 5b 73 71   must not be [sq
17440 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
17450 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20 70   finalized].** p
17460 72 69 6f 72 20 74 6f 20 74 68 69 73 20 72 6f 75  rior to this rou
17470 74 69 6e 65 20 72 65 74 75 72 6e 69 6e 67 2e 20  tine returning. 
17480 20 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 72   Otherwise the r
17490 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
174a0 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72 6f 62  ined.** and prob
174b0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
174c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
174d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
174e0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
174f0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
17500 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
17510 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
17520 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F13620}.**.** {
17530 46 31 33 36 32 31 7d 20 54 68 69 73 20 72 6f 75  F13621} This rou
17540 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
17550 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
17560 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
17570 2a 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61  * parameter in a
17580 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
17590 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
175a0 65 6e 74 5d 2e 20 7b 46 31 33 36 32 32 7d 0a 2a  ent]. {F13622}.*
175b0 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72  * Host parameter
175c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a  s of the form ":
175d0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
175e0 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20  r "$VVV" have a 
175f0 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73  name.** which is
17600 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41   the string ":AA
17610 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
17620 22 24 56 56 56 22 2e 20 0a 2a 2a 20 49 6e 20 6f  "$VVV". .** In o
17630 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
17640 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
17650 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20  $" or "@".** is 
17660 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
17670 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 20 20 7b   of the name.  {
17680 46 31 33 36 32 36 7d 0a 2a 2a 20 50 61 72 61 6d  F13626}.** Param
17690 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
176a0 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20  m "?" or "?NNN" 
176b0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a  have no name..**
176c0 0a 2a 2a 20 7b 46 31 33 36 32 33 7d 20 54 68 65  .** {F13623} The
176d0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
176e0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
176f0 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
17700 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 34 7d 20 49  **.** {F13624} I
17710 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73  f the value n is
17720 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
17730 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72   if the n-th par
17740 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
17750 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
17760 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b   is returned.  {
17770 46 31 33 36 32 35 7d 20 54 68 65 20 72 65 74 75  F13625} The retu
17780 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
17790 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 20  * always in the 
177a0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
177b0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
177c0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
177d0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
177e0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
177f0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
17800 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
17810 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17820 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
17830 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17840 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
17850 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
17860 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
17870 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
17880 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
17890 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
178a0 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a  e {F13640}.**.**
178b0 20 7b 46 31 33 36 34 31 7d 20 54 68 69 73 20 72   {F13641} This r
178c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
178d0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 20 68 6f  he index of a ho
178e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  st parameter wit
178f0 68 20 74 68 65 0a 2a 2a 20 67 69 76 65 6e 20 6e  h the.** given n
17900 61 6d 65 2e 20 20 7b 46 31 33 36 34 32 7d 20 54  ame.  {F13642} T
17910 68 65 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74  he name must mat
17920 63 68 20 65 78 61 63 74 6c 79 2e 20 20 7b 46 31  ch exactly.  {F1
17930 33 36 34 33 7d 0a 2a 2a 20 49 66 20 6e 6f 20 70  3643}.** If no p
17940 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68  arameter with th
17950 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 73 20  e given name is 
17960 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30 2e  found, return 0.
17970 0a 2a 2a 20 7b 46 31 33 36 34 34 7d 20 50 61 72  .** {F13644} Par
17980 61 6d 65 74 65 72 20 6e 61 6d 65 73 20 6d 75 73  ameter names mus
17990 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f 0a 69 6e  t be UTF8..*/.in
179a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
179b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
179c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
179d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
179e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
179f0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
17a00 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
17a10 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  red Statement {F
17a20 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  13660}.**.** {F1
17a30 33 36 36 31 7d 20 43 6f 6e 74 72 61 72 79 20 74  3661} Contrary t
17a40 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
17a50 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
17a60 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
17a70 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65  not.** reset the
17a80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
17a90 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
17aa0 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  on a .** [sqlite
17ab0 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
17ac0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 7b 46  d statement]. {F
17ad0 31 33 36 36 32 7d 20 55 73 65 20 74 68 69 73 20  13662} Use this 
17ae0 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65  routine to.** re
17af0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
17b00 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
17b10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17b20 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
17b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
17b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17b50 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
17b60 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
17b70 74 20 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a  t {F13710}.**.**
17b80 20 7b 46 31 33 37 31 31 7d 20 52 65 74 75 72 6e   {F13711} Return
17b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
17ba0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
17bb0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
17bc0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71  d by the .** [sq
17bd0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
17be0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
17bf0 65 6e 74 5d 2e 20 7b 46 31 33 37 31 32 7d 20 54  ent]. {F13712} T
17c00 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
17c10 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d  rns 0.** if pStm
17c20 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74  t is an SQL stat
17c30 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
17c40 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
17c50 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65  (for .** example
17c60 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f 0a   an UPDATE)..*/.
17c70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
17c80 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
17c90 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
17ca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17cb0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
17cc0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31  A Result Set {F1
17cd0 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  3720}.**.** {F13
17ce0 37 32 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69  721} These routi
17cf0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
17d00 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
17d10 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
17d20 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
17d30 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45  sult set of a SE
17d40 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20  LECT statement. 
17d50 20 7b 46 31 33 37 32 32 7d 20 54 68 65 20 73 71   {F13722} The sq
17d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
17d70 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
17d80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
17d90 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
17da0 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72  minated UTF8 str
17db0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
17dc0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
17dd0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
17de0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
17df0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
17e00 31 36 20 73 74 72 69 6e 67 2e 20 7b 46 31 33 37  16 string. {F137
17e10 32 33 7d 20 20 54 68 65 20 66 69 72 73 74 20 70  23}  The first p
17e20 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
17e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
17e40 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
17e50 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c  ement] that impl
17e60 65 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43  ements the SELEC
17e70 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  T statement..** 
17e80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17e90 65 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75  eter is the colu
17ea0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  mn number.  The 
17eb0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
17ec0 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e   is.** number 0.
17ed0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20  .**.** {F13724} 
17ee0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
17ef0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
17f00 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
17f10 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  r the .** [sqlit
17f20 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
17f30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
17f40 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
17f50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17f60 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  )].** or until t
17f70 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c  he next call sql
17f80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
17f90 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
17fa0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a  lumn_name16().**
17fb0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
17fc0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  umn..**.** {F137
17fd0 32 35 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  25} If sqlite3_m
17fe0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
17ff0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
18000 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
18010 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
18020 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
18030 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
18040 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
18050 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
18060 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
18070 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
18080 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
18090 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
180a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
180b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
180c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
180d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
180e0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
180f0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
18100 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
18110 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34 30  y Result {F13740
18120 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d  }.**.** {F13741}
18130 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18140 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
18150 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61  to determine wha
18160 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74  t column of what
18170 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69  .** table in whi
18180 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65  ch database a re
18190 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54  sult of a SELECT
181a0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
181b0 20 66 72 6f 6d 2e 0a 2a 2a 20 7b 46 31 33 37 34   from..** {F1374
181c0 32 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  2} The name of t
181d0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
181e0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
181f0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
18200 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
18210 46 38 20 6f 72 20 55 54 46 31 36 20 73 74 72 69  F8 or UTF16 stri
18220 6e 67 2e 20 20 7b 46 31 33 37 34 33 7d 20 54 68  ng.  {F13743} Th
18230 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
18240 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
18250 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
18260 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
18270 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
18280 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
18290 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
182a0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
182b0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
182c0 65 2e 20 7b 46 31 33 37 34 34 7d 0a 2a 2a 20 54  e. {F13744}.** T
182d0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
182e0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
182f0 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  l.** the [sqlite
18300 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
18310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
18320 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
18330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
18340 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
18350 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
18360 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
18370 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
18380 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
18390 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ing..**.** {F137
183a0 34 35 7d 20 54 68 65 20 6e 61 6d 65 73 20 72 65  45} The names re
183b0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
183c0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
183d0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
183e0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
183f0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
18400 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54  **.** {F13746} T
18410 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18420 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69  t to the followi
18430 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 0a 2a  ng calls is a .*
18440 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
18450 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  | compiled SQL s
18460 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 7b 46  tatement]..** {F
18470 31 33 37 34 37 7d 20 54 68 65 73 65 20 66 75 6e  13747} These fun
18480 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
18490 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
184a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
184b0 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74  eturned by .** t
184c0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
184d0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
184e0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
184f0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ument..**.** {F1
18500 33 37 34 38 7d 20 49 66 20 74 68 65 20 4e 74 68  3748} If the Nth
18510 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
18520 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
18530 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
18540 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72  on.** or subquer
18550 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
18560 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
18570 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
18580 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
18590 72 6e 20 4e 55 4c 4c 2e 20 20 7b 46 31 33 37 34  rn NULL.  {F1374
185a0 39 7d 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68  9} Otherwise, th
185b0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a  ey return the .*
185c0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  * name of the at
185d0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
185e0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
185f0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
18600 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61  ult.** column wa
18610 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
18620 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 35 30 7d  ..**.** {F13750}
18630 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68   As with all oth
18640 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
18650 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20  those postfixed 
18660 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
18670 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
18680 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20  ed strings, the 
18690 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
186a0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45  return UTF-8. {E
186b0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
186c0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
186d0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
186e0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
186f0 6c 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  led with the .**
18700 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
18710 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
18720 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
18730 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
18740 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66  * {U13751}.** If
18750 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
18760 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
18770 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
18780 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
18790 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
187a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
187b0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
187c0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
187d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
187e0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  ** undefined..*/
187f0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
18800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
18810 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
18820 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
18830 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
18840 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
18850 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
18860 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
18870 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
18880 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
18890 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
188a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
188b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
188c0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
188d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
188e0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
188f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
18900 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
18910 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
18920 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
18930 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
18940 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
18950 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
18960 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
18970 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
18980 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
18990 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13760}.**.** T
189a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
189b0 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33  er is a [sqlite3
189c0 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
189d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
189e0 20 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 49 66   .** {F13761} If
189f0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
18a00 69 73 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  is a SELECT stat
18a10 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
18a20 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
18a30 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
18a40 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
18a50 53 45 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c  SELECT is a tabl
18a60 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
18a70 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
18a80 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
18a90 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
18aa0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
18ab0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
18ac0 75 72 6e 65 64 2e 20 20 7b 46 31 33 37 36 32 7d  urned.  {F13762}
18ad0 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
18ae0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
18af0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
18b00 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
18b10 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
18b20 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
18b30 75 72 6e 65 64 2e 0a 2a 2a 20 7b 46 31 33 37 36  urned..** {F1376
18b40 33 7d 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  3} The returned 
18b50 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
18b60 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20   UTF-8 encoded. 
18b70 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f 72 20 65   {END} .** For e
18b80 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65 20 64  xample, in the d
18b90 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
18ba0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
18bb0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
18bc0 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65  );.**.** And the
18bd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
18be0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  ment compiled:.*
18bf0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
18c00 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
18c10 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73 20  **.** Then this 
18c20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
18c30 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
18c40 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
18c50 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75  e second.** resu
18c60 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  lt column (i==1)
18c70 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
18c80 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
18c90 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
18ca0 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a  .** (i==0)..**.*
18cb0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
18cc0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
18cd0 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20  yping.  So just 
18ce0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
18cf0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
18d00 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
18d10 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
18d20 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
18d30 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
18d40 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
18d50 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
18d60 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
18d70 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
18d80 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
18d90 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
18da0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
18db0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
18dc0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
18dd0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
18de0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
18df0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
18e00 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
18e10 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
18e20 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
18e30 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
18e40 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69  e3_stmt *, int i
18e50 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
18e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
18e70 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
18e80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
18e90 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20   .** CAPI3REF:  
18ea0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
18eb0 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30  Statement {F1320
18ec0 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  0}.**.** After a
18ed0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  n [sqlite3_stmt 
18ee0 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d  | SQL statement]
18ef0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
18f00 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a  ed with a call.*
18f10 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c  * to either [sql
18f20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18f30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
18f40 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
18f50 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  r to one of.** t
18f60 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
18f70 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
18f80 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
18f90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
18fa0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  ],.** then this 
18fb0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
18fc0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
18fd0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
18fe0 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74  luate the .** st
18ff0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
19000 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
19010 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
19020 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  is sqlite3_step(
19030 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
19040 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
19050 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
19060 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
19070 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
19080 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
19090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
190a0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
190b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
190c0 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
190d0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
190e0 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
190f0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
19100 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
19110 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
19120 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
19130 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
19140 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
19150 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
19160 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
19170 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
19180 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
19190 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  orted..**.** In 
191a0 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72  the lagacy inter
191b0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
191c0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
191d0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
191e0 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  SY], .** [SQLITE
191f0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
19200 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
19210 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
19220 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74  _MISUSE]..** Wit
19230 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
19240 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
19250 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f   other [SQLITE_O
19260 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  K | result code]
19270 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
19280 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
19290 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
192a0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
192b0 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a  ned as.** well..
192c0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  **.** [SQLITE_BU
192d0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
192e0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
192f0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
19300 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
19310 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
19320 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
19330 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73  s job.  If the s
19340 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f  tatement is a CO
19350 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MMIT.** or occur
19360 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
19370 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
19380 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
19390 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
193a0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
193b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
193c0 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64  not a COMMIT and
193d0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
193e0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
193f0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
19400 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
19410 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
19420 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
19430 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53  inuing..**.** [S
19440 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
19450 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
19460 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
19470 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
19480 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
19490 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
194a0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
194b0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
194c0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
194d0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
194e0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
194f0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
19500 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
19510 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
19520 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
19530 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tate..**.** If t
19540 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19550 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
19560 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
19570 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49  , then .** [SQLI
19580 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72  TE_ROW] is retur
19590 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
195a0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
195b0 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20  is ready.** for 
195c0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
195d0 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  e caller. The va
195e0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
195f0 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68  ssed using.** th
19600 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
19610 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61  n_int | column a
19620 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
19630 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
19640 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
19650 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
19660 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
19670 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51  data..** .** [SQ
19680 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
19690 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
196a0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
196b0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
196c0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
196d0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
196e0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
196f0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
19700 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
19710 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
19720 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
19730 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
19740 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
19750 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61  ** With the lega
19760 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
19770 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
19780 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c  ror code (exampl
19790 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e:.** [SQLITE_IN
197a0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
197b0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
197c0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
197d0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
197e0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
197f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
19800 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
19810 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  e.** [sqlite3_st
19820 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
19830 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68  atement].  In th
19840 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
19850 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
19860 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
19870 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
19880 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
19890 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
198a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
198b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
198c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
198d0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
198e0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
198f0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
19900 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   on a [sqlite3_s
19910 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
19920 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
19930 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
19940 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
19950 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
19960 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
19970 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75   had .** previou
19980 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
19990 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
199a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
199b0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
199c0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
199d0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
199e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
199f0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
19a00 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
19a10 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
19a20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
19a30 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
19a40 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
19a50 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  /b>.** In the le
19a60 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
19a70 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
19a80 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79  step() API alway
19a90 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
19aa0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a  ric error code,.
19ab0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
19ac0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
19ad0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
19ae0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
19af0 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  ** and [SQLITE_M
19b00 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
19b10 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
19b20 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
19b30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
19b40 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
19b50 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20  find one of the 
19b60 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c  specific.** [SQL
19b70 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75  ITE_ERROR | resu
19b80 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  lt codes] that b
19b90 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
19ba0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
19bb0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
19bc0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
19bd0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
19be0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
19bf0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
19c00 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
19c10 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
19c20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
19c30 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
19c40 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
19c50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
19c60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19c70 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
19c80 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
19c90 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
19ca0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
19cb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
19cc0 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d  , then the .** m
19cd0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 53 51  ore specific [SQ
19ce0 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73  LITE_ERROR | res
19cf0 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ult codes] are r
19d00 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
19d10 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
19d20 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
19d30 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
19d40 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
19d50 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
19d60 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
19d70 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
19d80 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
19d90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
19da0 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 46 31  a result set {F1
19db0 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3770}.**.** Retu
19dc0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
19dd0 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63   values in the c
19de0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
19df0 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a  e result set..**
19e00 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 41 66 74  .** {F13771} Aft
19e10 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
19e20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68  lite3_step()] th
19e30 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
19e40 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 74 68 69 73  TE_ROW],.** this
19e50 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c   routine.** will
19e60 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
19e70 20 76 61 6c 75 65 20 61 73 20 74 68 65 20 5b 73   value as the [s
19e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
19e90 75 6e 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e  unt()] function.
19ea0 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 0a 2a 2a 20  .** {F13772}.** 
19eb0 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  After [sqlite3_s
19ec0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
19ed0 6e 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44  ned an [SQLITE_D
19ee0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  ONE], [SQLITE_BU
19ef0 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51  SY], or.** a [SQ
19f00 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
19f10 6f 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66  or code], or bef
19f20 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
19f30 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a  p()] has been .*
19f40 2a 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  * called on the 
19f50 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
19f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
19f70 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  nt] for the firs
19f80 74 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20  t time,.** this 
19f90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
19fa0 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
19fb0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
19fc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
19fd0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
19fe0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
19ff0 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46 31  al Datatypes {F1
1a000 30 32 36 35 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  0265}.**.** {F10
1a010 32 36 36 7d 45 76 65 72 79 20 76 61 6c 75 65 20  266}Every value 
1a020 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
1a030 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
1a040 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
1a050 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
1a060 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
1a070 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
1a080 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
1a090 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
1a0a0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
1a0b0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
1a0c0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
1a0d0 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
1a0e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1a0f0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
1a100 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
1a110 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
1a120 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
1a130 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
1a140 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
1a150 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
1a160 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
1a170 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
1a180 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
1a190 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
1a1a0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
1a1b0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
1a1c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1a1d0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
1a1e0 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a  ITE3_TEXT not.**
1a1f0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
1a200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a210 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
1a220 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
1a230 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1a240 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
1a250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
1a260 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
1a270 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
1a280 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
1a290 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
1a2a0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
1a2b0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
1a2c0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
1a2d0 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
1a2e0 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61 6c 75  EF: Results Valu
1a2f0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20  es From A Query 
1a300 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13800}.**.** T
1a310 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1a320 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
1a330 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67   about.** a sing
1a340 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
1a350 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
1a360 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
1a370 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73   In every.** cas
1a380 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
1a390 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
1a3a0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71  r to the .** [sq
1a3b0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c  lite3_stmt | SQL
1a3c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1a3d0 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61   is being.** eva
1a3e0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
1a3f0 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74  ite3_stmt*] that
1a400 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
1a410 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
1a420 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a430 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
1a440 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65  ants) and.** the
1a450 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1a460 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
1a470 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
1a480 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
1a490 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  n .** should be 
1a4a0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
1a4b0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
1a4c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
1a4d0 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65  t.** has an inde
1a4e0 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66  x of 0..**.** If
1a4f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1a500 6e 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  nt is not curren
1a510 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
1a520 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
1a530 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d  the.** the colum
1a540 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
1a550 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
1a560 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
1a570 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  . .** These rout
1a580 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
1a590 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
1a5a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
1a5b0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
1a5c0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
1a5d0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
1a5e0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
1a5f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
1a600 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
1a610 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73  _finalize()] has
1a620 20 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65   been call subse
1a630 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
1a640 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
1a650 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1a660 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
1a670 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
1a680 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1a690 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
1a6a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
1a6b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
1a6c0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
1a6d0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
1a6e0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
1a6f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
1a700 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a710 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1a720 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
1a730 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
1a740 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
1a750 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
1a760 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
1a770 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1a780 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
1a790 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
1a7a0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
1a7b0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c    .**.** The sql
1a7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
1a7d0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1a7e0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  ns .** [SQLITE_I
1a7f0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
1a800 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
1a810 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
1a820 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
1a830 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  lt column.  The 
1a840 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
1a850 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
1a860 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
1a870 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
1a880 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
1a890 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
1a8a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
1a8b0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1a8c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a8d0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
1a8e0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
1a8f0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
1a900 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
1a910 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
1a920 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
1a930 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
1a940 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
1a950 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1a970 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
1a980 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
1a990 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1a9a0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
1a9b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
1a9c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
1a9d0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
1a9e0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
1a9f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
1aa00 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
1aa10 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
1aa20 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
1aa30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
1aa40 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74   .** routine ret
1aa50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1aa60 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
1aa70 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
1aa80 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
1aa90 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
1aaa0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
1aab0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
1aac0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
1aad0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
1aae0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
1aaf0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1ab00 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68   bytes..** If th
1ab10 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
1ab20 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
1ab30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1ab40 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
1ab50 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
1ab60 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
1ab70 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
1ab80 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
1ab90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
1aba0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1abb0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
1abc0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
1abd0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
1abe0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
1abf0 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
1ac00 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
1ac10 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61  string.  For cla
1ac20 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
1ac30 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
1ac40 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
1ac50 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
1ac60 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
1ac70 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
1ac80 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65  **.** Strings re
1ac90 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1aca0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
1acb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
1acc0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
1acd0 65 76 65 6e 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  even zero-length
1ace0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
1acf0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
1ad00 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
1ad10 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
1ad20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
1ad30 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
1ad40 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20  -length blob is 
1ad50 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
1ad60 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
1ad70 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
1ad80 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
1ad90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1ada0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
1adb0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1adc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
1add0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
1ade0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
1adf0 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61  in UTF-16 instea
1ae00 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a  d of UTF-8.  .**
1ae10 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
1ae20 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
1ae30 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
1ae40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  nt..**.** These 
1ae50 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
1ae60 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
1ae70 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
1ae80 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
1ae90 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
1aea0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
1aeb0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
1aec0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
1aed0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
1aee0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
1aef0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
1af00 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
1af10 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  do the conversio
1af20 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  n.** automatical
1af30 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
1af40 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
1af50 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
1af60 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70   that.** are app
1af70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
1af80 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
1af90 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
1afa0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
1afb0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
1afc0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
1afd0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
1afe0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
1aff0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
1b000 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
1b010 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
1b020 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
1b030 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
1b040 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
1b050 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
1b060 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
1b070 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
1b080 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
1b090 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
1b0a0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
1b0b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
1b0c0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
1b0d0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
1b0e0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
1b0f0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
1b100 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
1b110 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
1b120 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
1b130 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
1b140 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
1b150 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
1b160 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
1b170 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
1b180 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
1b190 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e  as for INTEGER->
1b1a0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
1b1b0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
1b1c0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
1b1d0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
1b1e0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
1b1f0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
1b200 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
1b210 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
1b220 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
1b230 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
1b240 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
1b250 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
1b260 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
1b270 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
1b280 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
1b290 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
1b2a0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
1b2b0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
1b2c0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
1b2d0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
1b2e0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
1b2f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
1b300 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
1b310 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
1b320 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
1b330 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
1b340 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
1b350 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
1b360 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
1b370 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
1b380 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
1b390 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
1b3a0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
1b3b0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
1b3c0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
1b3d0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
1b3e0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
1b3f0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
1b400 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
1b410 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
1b420 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
1b430 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
1b440 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
1b450 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
1b460 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
1b470 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
1b480 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
1b490 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75  as its.** on equ
1b4a0 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  avalent internal
1b4b0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
1b4c0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
1b4d0 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
1b4e0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
1b4f0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
1b500 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
1b510 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
1b520 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
1b530 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
1b540 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
1b550 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
1b560 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
1b570 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
1b580 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
1b590 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
1b5a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1b5b0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
1b5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1b5d0 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
1b5e0 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a  invalidated. .**
1b5f0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
1b600 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
1b610 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
1b620 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
1b630 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
1b640 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1b650 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
1b660 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
1b670 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
1b680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1b690 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ) .**          o
1b6a0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
1b6b0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
1b6c0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
1b6d0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
1b6e0 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74            need t
1b6f0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
1b700 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c  e string.</p></l
1b710 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
1b720 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
1b730 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
1b740 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
1b750 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
1b760 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1b770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1b780 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
1b790 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
1b7a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1b7b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
1b7c0 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69   UTF-16.</p></li
1b7d0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
1b7e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
1b7f0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
1b800 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
1b810 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
1b820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
1b830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1b840 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
1b850 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
1b860 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
1b870 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
1b880 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20  -8.</p></li>.** 
1b890 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
1b8a0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
1b8b0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
1b8c0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
1b8d0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
1b8e0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
1b8f0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
1b900 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
1b910 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
1b920 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
1b930 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
1b940 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
1b950 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
1b960 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
1b970 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
1b980 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
1b990 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
1b9a0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
1b9b0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
1b9c0 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  me it is.** not 
1b9d0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
1b9e0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
1b9f0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
1ba00 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a  nvalidated.  .**
1ba10 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
1ba20 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
1ba30 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
1ba40 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
1ba50 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
1ba60 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
1ba70 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
1ba80 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73    <ul>.**  <li>s
1ba90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1baa0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
1bab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1bac0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
1bad0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
1bae0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
1baf0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
1bb00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
1bb10 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
1bb20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
1bb30 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
1bb40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
1bb50 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
1bb60 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
1bb70 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
1bb80 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
1bb90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1bba0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
1bbb0 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72  mn_blob(),.** or
1bbc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1bbd0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
1bbe0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
1bbf0 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  lt into the desi
1bc00 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74  red.** format, t
1bc10 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
1bc20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
1bc30 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
1bc40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
1bc50 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a  .** find the siz
1bc60 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
1bc70 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
1bc80 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  l to sqlite3_col
1bc90 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
1bca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1bcb0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
1bcc0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
1bcd0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20  umn_bytes16().  
1bce0 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69  And do not.** mi
1bcf0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
1bd00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
1bd10 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
1bd20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1bd30 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
1bd40 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
1bd50 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
1bd60 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
1bd70 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
1bd80 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
1bd90 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
1bda0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
1bdb0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
1bdc0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1bdd0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
1bde0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
1bdf0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
1be00 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
1be10 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73  .** and blobs is
1be20 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
1be30 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
1be40 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
1be50 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
1be60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1be70 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
1be80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1be90 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a  ()], etc. into .
1bea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1beb0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
1bec0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1bed0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
1bee0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
1bef0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
1bf00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1bf10 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
1bf20 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
1bf30 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
1bf40 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
1bf50 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
1bf60 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
1bf70 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
1bf80 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
1bf90 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
1bfa0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1bfb0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
1bfc0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1bfd0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f  TE_NOMEM]..*/.co
1bfe0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1bff0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
1c000 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c010 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
1c020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
1c030 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c040 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
1c050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
1c060 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
1c070 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
1c080 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
1c090 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
1c0a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1c0b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
1c0c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
1c0d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c0e0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
1c0f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
1c100 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
1c110 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
1c120 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
1c130 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
1c140 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
1c150 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c160 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
1c170 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1c180 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
1c190 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
1c1a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1c1b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
1c1c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
1c1d0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
1c1e0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
1c1f0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
1c200 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
1c210 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1c220 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
1c230 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1c240 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 30 30  t Object {F13300
1c250 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
1c260 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
1c270 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
1c280 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a  d to delete a .*
1c290 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
1c2a0 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  | compiled SQL s
1c2b0 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68  tatement]. If th
1c2c0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  e statement was.
1c2d0 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63  ** executed succ
1c2e0 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74  essfully, or not
1c2f0 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
1c300 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b  , then SQLITE_OK
1c310 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1c320 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
1c330 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1c340 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a  ailed then an .*
1c350 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
1c360 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72  | error code] or
1c370 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
1c380 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65  EAD | extended e
1c390 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73  rror code].** is
1c3a0 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a   returned. .**.*
1c3b0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
1c3c0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
1c3d0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
1c3e0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1c3f0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1c400 33 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c  3_stmt | virtual
1c410 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74   machine].  If t
1c420 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
1c430 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63  ne has not .** c
1c440 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
1c450 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
1c460 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
1c470 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
1c480 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
1c490 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
1c4a0 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71  rrupt.  (See [sq
1c4b0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c4c0 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c  )].) .** Incompl
1c4d0 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20  ete updates may 
1c4e0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1c4f0 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  nd transactions 
1c500 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20  cancelled,  .** 
1c510 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
1c520 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
1c530 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  and the .** [SQL
1c540 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75  ITE_ERROR | resu
1c550 6c 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  lt code] returne
1c560 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
1c570 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74  E_ABORT]..*/.int
1c580 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
1c590 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
1c5a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1c5b0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
1c5c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1c5d0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33  ent Object {F133
1c5e0 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  30}.**.** The sq
1c5f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
1c600 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
1c610 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a 2a 20   to reset a .** 
1c620 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
1c630 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1c640 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
1c650 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ** back to its i
1c660 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
1c670 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
1c680 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
1c690 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
1c6a0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
1c6b0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
1c6c0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
1c6d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1c6e0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
1c6f0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
1c700 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
1c710 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
1c720 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
1c730 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
1c740 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74  bindings..*/.int
1c750 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
1c760 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1c770 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1c780 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
1c790 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
1c7a0 63 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a  ctions {F16100}.
1c7b0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
1c7c0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
1c7d0 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
1c7e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
1c7f0 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a  or aggregates.**
1c800 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
1c810 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
1c820 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
1c830 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
1c840 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69  ates.  The.** di
1c850 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
1c860 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
1c870 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
1c880 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
1c890 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  ** name of the (
1c8a0 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
1c8b0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69   or aggregate, i
1c8c0 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
1c8d0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1c8e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1c8f0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66  n() and UTF-16 f
1c900 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
1c910 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
1c920 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1c930 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1c940 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62  [sqlite3 | datab
1c950 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74  ase handle] that
1c960 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51   holds the.** SQ
1c970 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
1c980 67 72 65 67 61 74 65 20 69 73 20 74 6f 20 62 65  gregate is to be
1c990 20 61 64 64 65 64 20 6f 72 20 72 65 64 65 66 69   added or redefi
1c9a0 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65  ned. If a single
1c9b0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
1c9c0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
1c9d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69  atabase handle i
1c9e0 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
1c9f0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  SQL.** functions
1ca00 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6d   or aggregates m
1ca10 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
1ca20 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63  ividually to eac
1ca30 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61  h database.** ha
1ca40 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63 68 20  ndle with which 
1ca50 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65  they will be use
1ca60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
1ca70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1ca80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1ca90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
1caa0 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f   be created.** o
1cab0 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  r redefined..** 
1cac0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
1cad0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
1cae0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
1caf0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
1cb00 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   .** zero-termin
1cb10 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
1cb20 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
1cb30 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
1cb40 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
1cb50 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
1cb60 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
1cb70 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
1cb80 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
1cb90 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  ill result in an
1cba0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
1cbb0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ror..**.** The t
1cbc0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1cbd0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1cbe0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
1cbf0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1cc00 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
1cc10 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
1cc20 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
1cc30 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
1cc40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
1cc50 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
1cc60 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
1cc70 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
1cc80 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
1cc90 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
1cca0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
1ccb0 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  at .** [SQLITE_U
1ccc0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
1ccd0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
1cce0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
1ccf0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
1cd00 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
1cd10 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1cd20 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
1cd30 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
1cd40 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
1cd50 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
1cd60 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
1cd70 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
1cd80 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
1cd90 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
1cda0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
1cdb0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
1cdc0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
1cdd0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
1cde0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
1cdf0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
1ce00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
1ce10 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
1ce20 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
1ce30 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
1ce40 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
1ce50 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
1ce60 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
1ce70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1ce80 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
1ce90 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
1cea0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
1ceb0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
1cec0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
1ced0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
1cee0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
1cef0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
1cf00 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
1cf10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1cf20 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
1cf30 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78  care what.** tex
1cf40 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  t encoding is us
1cf50 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
1cf60 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
1cf70 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54  uld be.** [SQLIT
1cf80 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
1cf90 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
1cfa0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
1cfb0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
1cfc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1cfd0 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * of the functio
1cfe0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
1cff0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
1d000 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  r using.** [sqli
1d010 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
1d020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
1d030 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
1d040 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
1d050 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
1d060 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
1d070 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
1d080 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
1d090 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
1d0a0 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  t the SQL.** fun
1d0b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
1d0c0 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
1d0d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
1d0e0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
1d0f0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78  tion of.** the x
1d100 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  Func callback on
1d110 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
1d120 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
1d130 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a  ed as the xStep.
1d140 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61  ** and xFinal pa
1d150 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
1d160 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
1d170 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
1d180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1d190 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78  * of xStep and x
1d1a0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
1d1b0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
1d1c0 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
1d1d0 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74  lete an.** exist
1d1e0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
1d1f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
1d200 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
1d210 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
1d220 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ** callback..**.
1d230 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
1d240 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
1d250 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
1d260 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
1d270 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
1d280 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
1d290 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
1d2a0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
1d2b0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
1d2c0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
1d2d0 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78  ng perferred tex
1d2e0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
1d2f0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
1d300 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1d310 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
1d320 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
1d330 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
1d340 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
1d350 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71   used..*/.int sq
1d360 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1d370 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
1d380 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   *,.  const char
1d390 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
1d3a0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
1d3b0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
1d3c0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78  oid*,.  void (*x
1d3d0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
1d3e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
1d3f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
1d400 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
1d410 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
1d420 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
1d430 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
1d440 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
1d450 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
1d460 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1d470 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
1d480 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e3*,.  const voi
1d490 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
1d4a0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
1d4b0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
1d4c0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a  void*,.  void (*
1d4d0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
1d4e0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
1d4f0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
1d500 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
1d510 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
1d520 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
1d530 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
1d540 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
1d550 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
1d560 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
1d570 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32   Encodings {F102
1d580 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  67}.**.** These 
1d590 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
1d5a0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
1d5b0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
1d5c0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
1d5d0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
1d5e0 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
1d5f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d600 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
1d610 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
1d620 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
1d630 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
1d640 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
1d650 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
1d660 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
1d670 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
1d680 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
1d690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d6a0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
1d6b0 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
1d6c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
1d6d0 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
1d6e0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
1d6f0 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
1d700 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1d710 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
1d720 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d730 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f  Obsolete Functio
1d740 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ns.**.** These f
1d750 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c  unctions are all
1d760 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20   now obsolete.  
1d770 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
1d780 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
1d790 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
1d7a0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
1d7b0 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   we continue to 
1d7c0 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65  support.** these
1d7d0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77   functions.  How
1d7e0 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f  ever, new develo
1d7f0 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73  pment projects s
1d800 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
1d810 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
1d820 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
1d830 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
1d840 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
1d850 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
1d860 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
1d870 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
1d880 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64   you want they d
1d890 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
1d8a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
1d8b0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
1d8c0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
1d8d0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
1d8e0 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
1d8f0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
1d900 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
1d910 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
1d920 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
1d930 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
1d940 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c  (void);.void sql
1d950 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
1d960 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nup(void);.int s
1d970 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
1d980 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
1d990 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
1d9a0 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74  int),void*,sqlit
1d9b0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
1d9c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
1d9d0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
1d9e0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
1d9f0 75 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a  ues {F15100}.**.
1da00 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
1da10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1da20 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
1da30 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
1da40 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
1da50 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
1da60 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
1da70 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
1da80 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
1da90 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
1daa0 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
1dab0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
1dac0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
1dad0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
1dae0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
1daf0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
1db00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1db10 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
1db20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1db30 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
1db40 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
1db50 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
1db60 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
1db70 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
1db80 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
1db90 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
1dba0 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
1dbb0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
1dbc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
1dbd0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
1dbe0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
1dbf0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
1dc00 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
1dc10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
1dc20 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
1dc30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1dc40 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
1dc50 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
1dc60 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1dc70 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
1dc80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1dc90 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
1dca0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
1dcb0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  g .** [sqlite3_c
1dcc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c  olumn_blob | sql
1dcd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f  ite3_column_* ro
1dce0 75 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74  utines] except t
1dcf0 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f  hat .** these ro
1dd00 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
1dd10 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  ngle [sqlite3_va
1dd20 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e  lue*] pointer in
1dd30 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b  stead.** of an [
1dd40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
1dd50 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
1dd60 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
1dd70 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ber..**.** The s
1dd80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
1dd90 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
1dda0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36  extracts a UTF16
1ddb0 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
1ddc0 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
1ddd0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
1dde0 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
1ddf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1de00 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
1de10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
1de20 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
1de30 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
1de40 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
1de50 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
1de60 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
1de70 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ctively..**.** T
1de80 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1de90 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
1dea0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1deb0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
1dec0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
1ded0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
1dee0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
1def0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
1df00 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
1df10 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
1df20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
1df30 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
1df40 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
1df50 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
1df60 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
1df70 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
1df80 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69  other.** words i
1df90 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
1dfa0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
1dfb0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
1dfc0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
1dfd0 6e 76 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e 65  nversion is done
1dfe0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
1dff0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
1e000 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c  s.  The .** [SQL
1e010 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
1e020 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
1e030 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
1e040 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
1e050 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
1e060 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
1e070 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
1e080 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1e090 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f   is returned fro
1e0a0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
1e0b0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
1e0c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
1e0d0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
1e0e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
1e0f0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
1e100 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
1e110 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
1e120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
1e130 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
1e140 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
1e150 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
1e160 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
1e170 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1e180 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a  text16()].  .**.
1e190 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e1a0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
1e1b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
1e1c0 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
1e1d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
1e1e0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73  t supplied the s
1e1f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61  qlite3_value* pa
1e200 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c  rameters..** Or,
1e210 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
1e220 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20  value* argument 
1e230 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  comes from the [
1e240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1e250 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  alue()].** inter
1e260 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65  face, then these
1e270 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1e280 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
1e290 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a  the same thread.
1e2a0 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c  ** that ran [sql
1e2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1e2c0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 63 6f 6e 73  e()]..**.*/.cons
1e2d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1e2e0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
1e2f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1e300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
1e310 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
1e320 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1e330 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
1e340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
1e350 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
1e360 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
1e370 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1e380 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
1e390 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
1e3a0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
1e3b0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
1e3c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
1e3d0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
1e3e0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
1e3f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
1e400 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
1e410 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1e420 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
1e430 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
1e440 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e450 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
1e460 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
1e470 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
1e480 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
1e490 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
1e4a0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1e4b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
1e4c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
1e4d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
1e4e0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
1e4f0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
1e500 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e510 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
1e520 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
1e530 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a  text {F16210}.**
1e540 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
1e550 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
1e560 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
1e570 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
1e580 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
1e590 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
1e5a0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
1e5b0 73 74 61 74 65 2e 20 20 0a 2a 2a 20 7b 46 31 36  state.  .** {F16
1e5c0 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 74  211} The first t
1e5d0 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
1e5e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
1e5f0 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  t() routine is.*
1e600 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  * is called for 
1e610 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
1e620 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61  regate, SQLite a
1e630 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20  llocates nBytes 
1e640 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72  of memory.** zer
1e650 6f 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  os that memory, 
1e660 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
1e670 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a 20  inter to it..** 
1e680 7b 46 31 36 32 31 32 7d 20 4f 6e 20 73 65 63 6f  {F16212} On seco
1e690 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1e6a0 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  t calls to sqlit
1e6b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1e6c0 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68  text().** for th
1e6d0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
1e6e0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c   function index,
1e6f0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
1e700 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 45   is returned. {E
1e710 4e 44 7d 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ND}.** The imple
1e720 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
1e730 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
1e740 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e  n use the return
1e750 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
1e760 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
1e770 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 53 51 4c  .** {F16213} SQL
1e780 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
1e790 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
1e7a0 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
1e7b0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
1e7c0 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
1e7d0 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  es. {END}.**.** 
1e7e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1e7f0 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
1e800 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20  copy of the .** 
1e810 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1e820 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
1e830 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
1e840 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
1e850 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1e860 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
1e870 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
1e880 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
1e890 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
1e8a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
1e8b0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
1e8c0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
1e8d0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
1e8e0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
1e8f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
1e900 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
1e910 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
1e920 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
1e930 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
1e940 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
1e950 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
1e960 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  a For Functions 
1e970 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F16240}.**.** {
1e980 46 31 36 32 34 31 7d 20 54 68 65 20 73 71 6c 69  F16241} The sqli
1e990 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
1e9a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1e9b0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
1e9c0 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
1e9d0 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
1e9e0 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
1e9f0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
1ea00 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b 73  ** of the the [s
1ea10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1ea20 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
1ea30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1ea40 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
1ea50 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
1ea60 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
1ea70 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
1ea80 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
1ea90 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a  nction. {END}.**
1eaa0 0a 2a 2a 20 7b 55 31 36 32 34 33 7d 20 54 68 69  .** {U16243} Thi
1eab0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
1eac0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
1ead0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
1eae0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
1eaf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1eb00 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
1eb10 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
1eb20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1eb30 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
1eb40 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1eb50 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
1eb60 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46  uxiliary Data {F
1eb70 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16270}.**.** The
1eb80 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
1eb90 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
1eba0 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
1ebb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
1ebc0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
1ebd0 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75  a-data with argu
1ebe0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
1ebf0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
1ec00 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
1ec10 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
1ec20 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
1ec30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
1ec40 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
1ec50 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
1ec60 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
1ec70 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
1ec80 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65  meta-data may be
1ec90 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
1eca0 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
1ecb0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
1ecc0 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
1ecd0 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
1ece0 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
1ecf0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
1ed00 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
1ed10 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
1ed20 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
1ed30 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20  as.** meta-data 
1ed40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1ed50 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
1ed60 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
1ed70 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
1ed80 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
1ed90 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
1eda0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
1edb0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
1edc0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
1edd0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
1ede0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
1edf0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
1ee00 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
1ee10 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1ee20 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
1ee30 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
1ee40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37  on..**.** {F1627
1ee50 31 7d 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  1}.** The sqlite
1ee60 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
1ee70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1ee80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1ee90 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
1eea0 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
1eeb0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1eec0 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
1eed0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
1eee0 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
1eef0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1ef00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
1ef10 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 32 37 32 7d  ion..** {F16272}
1ef20 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61   If no meta-data
1ef30 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62   has been ever b
1ef40 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
1ef50 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Nth.** argument 
1ef60 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
1ef70 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72 65   or if the coore
1ef80 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
1ef90 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68  n parameter.** h
1efa0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
1efb0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
1efc0 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c  as set, then sql
1efd0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1efe0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1eff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1f000 0a 2a 2a 20 7b 46 31 36 32 37 35 7d 20 54 68 65  .** {F16275} The
1f010 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
1f020 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
1f030 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 2d   saves the meta-
1f040 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
1f050 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
1f060 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
1f070 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68 65  eta-data for the
1f080 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
1f090 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
1f0a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
1f0b0 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 53 75 62  ction. {END} Sub
1f0c0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
1f0d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
1f0e0 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
1f0f0 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
1f100 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
1f110 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
1f120 64 2e 20 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20  d. .** {F16277} 
1f130 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
1f140 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
1f150 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
1f160 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f  ctor .** functio
1f170 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
1f180 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f190 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1f1a0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
1f1b0 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20 74  meta-data when t
1f1c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1f1d0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
1f1e0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
1f1f0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
1f200 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
1f210 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
1f220 6d 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44 7d  mes first. {END}
1f230 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
1f240 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73  ce, meta-data is
1f250 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
1f260 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
1f270 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
1f280 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
1f290 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
1f2a0 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
1f2b0 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
1f2c0 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
1f2d0 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
1f2e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1f2f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
1f300 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
1f310 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
1f320 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1f330 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
1f340 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
1f350 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
1f360 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
1f370 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
1f380 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
1f390 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
1f3a0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
1f3b0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
1f3c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f3d0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
1f3e0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
1f3f0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
1f400 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10280}.**.** T
1f410 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
1f420 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64   value for the d
1f430 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
1f440 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
1f450 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
1f460 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
1f470 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
1f480 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
1f490 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
1f4a0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
1f4b0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
1f4c0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
1f4d0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
1f4e0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
1f4f0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
1f500 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
1f510 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1f520 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20  destroyed.  The 
1f530 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
1f540 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
1f550 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
1f560 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
1f570 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
1f580 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
1f590 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
1f5a0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
1f5b0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
1f5c0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
1f5d0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
1f5e0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
1f5f0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
1f600 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
1f610 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
1f620 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
1f630 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
1f640 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
1f650 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
1f660 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
1f670 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
1f680 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
1f690 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
1f6a0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
1f6b0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
1f6c0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
1f6d0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
1f6e0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
1f6f0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
1f700 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
1f710 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
1f720 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a  n {F16400}.**.**
1f730 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1f740 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
1f750 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
1f760 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
1f770 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
1f780 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
1f790 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
1f7a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
1f7b0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
1f7c0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
1f7d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
1f7e0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
1f7f0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
1f800 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
1f810 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
1f820 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
1f830 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f840 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
1f850 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
1f860 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
1f870 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
1f880 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
1f890 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
1f8a0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
1f8b0 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
1f8c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f8d0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
1f8e0 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
1f8f0 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
1f900 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
1f910 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 32 7d 20  .**.** {F16402} 
1f920 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
1f930 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
1f940 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
1f950 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
1f960 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
1f970 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
1f980 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
1f990 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
1f9a0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
1f9b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1f9c0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
1f9d0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
1f9e0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
1f9f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a  ird parameter. .
1fa00 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20  ** {F16403} The 
1fa10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
1fa20 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61  eroblob() inerfa
1fa30 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
1fa40 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
1fa50 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
1fa60 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
1fa70 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
1fa80 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
1fa90 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
1faa0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
1fab0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1fac0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
1fad0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30  er..**.** {F1640
1fae0 37 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  7} The sqlite3_r
1faf0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
1fb00 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
1fb10 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
1fb20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1fb30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
1fb40 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
1fb50 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
1fb60 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
1fb70 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
1fb80 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54  **.** {F16409} T
1fb90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
1fba0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
1fbb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1fbc0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
1fbd0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
1fbe0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
1fbf0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
1fc00 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
1fc10 20 7b 46 31 36 34 31 31 7d 20 53 51 4c 69 74 65   {F16411} SQLite
1fc20 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
1fc30 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
1fc40 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
1fc50 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
1fc60 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
1fc70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1fc80 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
1fc90 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
1fca0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 7b 46  rror message. {F
1fcb0 31 36 34 31 32 7d 20 53 51 4c 69 74 65 20 69 6e  16412} SQLite in
1fcc0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
1fcd0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
1fce0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
1fcf0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
1fd00 20 61 73 20 55 54 46 38 2e 20 20 7b 46 31 36 34   as UTF8.  {F164
1fd10 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  13} SQLite.** in
1fd20 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
1fd30 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
1fd40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
1fd50 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e 61  ) as UTF16 in na
1fd60 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
1fd70 65 72 2e 20 20 7b 46 31 36 34 31 34 7d 20 49 66  er.  {F16414} If
1fd80 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1fd90 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1fda0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
1fdb0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
1fdc0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
1fdd0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
1fde0 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
1fdf0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
1fe00 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
1fe10 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
1fe20 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
1fe30 2e 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 49 66  ..** {F16415} If
1fe40 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1fe50 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1fe60 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
1fe70 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
1fe80 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
1fe90 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
1fea0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
1feb0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
1fec0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
1fed0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
1fee0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
1fef0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
1ff00 0a 2a 2a 20 7b 46 31 36 34 31 37 7d 20 54 68 65  .** {F16417} The
1ff10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1ff20 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
1ff30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1ff40 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
1ff50 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69   make a copy pri
1ff60 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1ff70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
1ff80 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
1ff90 65 79 20 72 65 74 75 72 6e 2e 20 20 7b 45 4e 44  ey return.  {END
1ffa0 7d 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c  } Hence, the cal
1ffb0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
1ffc0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
1ffd0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
1ffe0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
1fff0 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
20000 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31  m..**.** {F16421
20010 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  } The sqlite3_re
20020 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
20030 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
20040 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f  QLite.** to thro
20050 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63  w an error indic
20060 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
20070 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
20080 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70  o long.** to rep
20090 72 65 73 65 6e 74 2e 20 20 7b 46 31 36 34 32 32  resent.  {F16422
200a0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  } The sqlite3_re
200b0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
200c0 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65 73  erface.** causes
200d0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
200e0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69 6e   an exception in
200f0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
20100 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  e a.** memory al
20110 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
20120 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 31 7d 20  .**.** {F16431} 
20130 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
20140 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
20150 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
20160 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
20170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
20180 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
20190 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
201a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
201b0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
201c0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
201d0 6e 74 2e 0a 2a 2a 20 7b 46 31 36 34 33 32 7d 20  nt..** {F16432} 
201e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
201f0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
20200 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
20210 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
20220 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
20230 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
20240 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
20250 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
20260 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
20270 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
20280 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ment..**.** {F16
20290 34 33 37 7d 20 54 68 65 20 73 71 6c 69 74 65 33  437} The sqlite3
202a0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
202b0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
202c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
202d0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
202e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
202f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
20300 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 31 7d  ..**.** {F16441}
20310 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
20320 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
20330 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
20340 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33  6(), .** sqlite3
20350 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
20360 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
20370 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
20380 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
20390 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
203a0 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
203b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
203c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
203d0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
203e0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
203f0 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
20400 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
20410 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
20420 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
20430 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
20440 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
20450 76 65 6c 79 2e 0a 2a 2a 20 7b 46 31 36 34 34 32  vely..** {F16442
20460 7d 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  } SQLite takes t
20470 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
20480 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
20490 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
204a0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
204b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
204c0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
204d0 61 63 65 73 2e 0a 2a 2a 20 7b 46 31 36 34 34 34  aces..** {F16444
204e0 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  } If the 3rd par
204f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
20500 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
20510 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
20520 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
20530 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
20540 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
20550 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
20560 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  er .** through t
20570 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
20580 61 72 61 63 74 65 72 2e 0a 2a 2a 20 7b 46 31 36  aracter..** {F16
20590 34 34 37 7d 20 49 66 20 74 68 65 20 33 72 64 20  447} If the 3rd 
205a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
205b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
205c0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
205d0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
205e0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
205f0 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
20600 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
20610 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
20620 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
20630 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
20640 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
20650 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
20660 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
20670 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 49 66 20  .** {F16451} If 
20680 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
20690 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
206a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
206b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
206c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
206d0 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
206e0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
206f0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
20700 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
20710 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
20720 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c  n the text or bl
20730 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  ob result when i
20740 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
20750 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
20760 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 33 7d  ult..** {F16453}
20770 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
20780 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
20790 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
207a0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
207b0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
207c0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
207d0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
207e0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
207f0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73  en.** SQLite ass
20800 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
20810 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c  xt or blob resul
20820 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70  t is constant sp
20830 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20  ace and.** does 
20840 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70 61  not copy the spa
20850 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  ce or call a des
20860 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
20870 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
20880 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
20890 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 49  t..** {F16454} I
208a0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
208b0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
208c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
208d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
208e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
208f0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
20900 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
20910 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
20920 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
20930 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
20940 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
20950 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
20960 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
20970 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
20980 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
20990 2a 0a 2a 2a 20 7b 46 31 36 34 36 31 7d 20 54 68  *.** {F16461} Th
209a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
209b0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
209c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
209d0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
209e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
209f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
20a00 61 20 63 6f 70 79 20 74 68 65 20 5b 73 71 6c 69  a copy the [sqli
20a10 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
20a20 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
20a30 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
20a40 74 65 72 2e 20 20 7b 46 31 36 34 36 33 7d 20 54  ter.  {F16463} T
20a50 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
20a60 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
20a70 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
20a80 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
20a90 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
20aa0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 76   that [sqlite3_v
20ab0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
20ac0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
20ad0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
20ae0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
20af0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
20b00 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
20b10 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
20b20 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 36 34 39  rm..**.** {U1649
20b30 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  1} These routine
20b40 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
20b50 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
20b60 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a 2a  ferent thread .*
20b70 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
20b80 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
20b90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20ba0 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
20bb0 72 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 20  recieved.** the 
20bc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
20bd0 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
20be0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
20bf0 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
20c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
20c10 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
20c20 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
20c30 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
20c40 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
20c50 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
20c60 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
20c70 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
20c80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
20c90 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
20ca0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
20cb0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
20cc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
20cd0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
20ce0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
20cf0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
20d00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
20d10 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
20d20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
20d30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
20d40 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
20d50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
20d60 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
20d70 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
20d80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
20d90 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
20da0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
20db0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
20dc0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20dd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
20de0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
20df0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
20e00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
20e10 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
20e20 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
20e30 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
20e40 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
20e50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
20e60 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
20e70 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
20e80 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
20e90 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
20ea0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
20eb0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
20ec0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
20ed0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
20ee0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
20ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
20f00 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
20f10 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
20f20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
20f30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
20f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
20f50 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
20f60 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
20f70 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
20f80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
20f90 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
20fa0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
20fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20fc0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
20fd0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
20fe0 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F16600}.**.** {
20ff0 46 31 36 36 30 31 7d 0a 2a 2a 20 54 68 65 73 65  F16601}.** These
21000 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
21010 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63  sed to add new c
21020 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
21030 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71  es to the.** [sq
21040 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73  lite3*] handle s
21050 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
21060 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
21070 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 32 7d 0a  .**.** {F16602}.
21080 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
21090 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
210a0 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
210b0 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
210c0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
210d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
210e0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
210f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
21100 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
21110 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
21120 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
21130 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
21140 31 36 28 29 2e 20 7b 46 31 36 36 30 33 7d 20 49  16(). {F16603} I
21150 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
21160 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
21170 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
21180 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
21190 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34  t..**.** {F16604
211a0 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  }.** The third a
211b0 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f  rgument may be o
211c0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
211d0 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  nts [SQLITE_UTF8
211e0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  ],.** [SQLITE_UT
211f0 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54  F16LE] or [SQLIT
21200 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
21210 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
21220 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
21230 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
21240 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
21250 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
21260 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
21270 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
21280 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6f   little-endian o
21290 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
212a0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
212b0 2e 20 7b 46 31 36 36 30 35 7d 20 54 68 65 0a 2a  . {F16605} The.*
212c0 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
212d0 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
212e0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
212f0 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
21300 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
21310 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
21320 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
21330 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
21340 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31  rings.** of UTF1
21350 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21360 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
21370 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
21380 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 37 7d 0a  .**.** {F16607}.
21390 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
213a0 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
213b0 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
213c0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
213d0 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
213e0 74 2e 20 7b 46 31 36 36 30 39 7d 20 49 66 20 69  t. {F16609} If i
213f0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
21400 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
21410 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
21420 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
21430 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
21440 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
21450 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 7b 46   anymore)..** {F
21460 31 36 36 31 31 7d 20 45 61 63 68 20 74 69 6d 65  16611} Each time
21470 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21480 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e  .** supplied fun
21490 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
214a0 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61  , it is passed a
214b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
214c0 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  d* passed as.** 
214d0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
214e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
214f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
21500 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
21510 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
21520 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73  16() as its firs
21530 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
21540 2a 2a 20 7b 46 31 36 36 31 32 7d 0a 2a 2a 20 54  ** {F16612}.** T
21550 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67  he remaining arg
21560 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70  uments to the ap
21570 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
21580 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
21590 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
215a0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
215b0 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61  by a [length, da
215c0 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta] pair and enc
215d0 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
215e0 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
215f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
21600 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
21610 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
21620 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
21630 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e   registered. {EN
21640 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  D} The applicati
21650 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
21660 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
21670 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
21680 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
21690 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74  positive if.** t
216a0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
216b0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
216c0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
216d0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
216e0 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e  nd.** string. i.
216f0 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
21700 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  RING2)..**.** {F
21710 31 36 36 31 35 7d 0a 2a 2a 20 54 68 65 20 73 71  16615}.** The sq
21720 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
21730 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
21740 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
21750 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
21760 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74  ).** excapt that
21770 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
21780 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
21790 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
217a0 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
217b0 6c 61 74 69 6f 6e 2e 20 20 7b 46 31 36 36 31 37  lation.  {F16617
217c0 7d 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  } The destructor
217d0 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   is called when 
217e0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
217f0 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e  .** destroyed an
21800 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  d is passed a co
21810 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  py of the fourth
21820 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a   parameter void*
21830 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74   pointer.** of t
21840 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
21850 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
21860 2e 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 20 43  ..** {F16618}  C
21870 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65  ollations are de
21880 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20  stroyed when.** 
21890 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
218a0 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
218b0 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
218c0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
218d0 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65  ctions.** or whe
218e0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  n the [sqlite3*]
218f0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
21900 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
21910 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
21920 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
21930 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
21940 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
21950 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
21960 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
21970 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
21980 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
21990 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
219a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
219b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
219c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
219d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
219e0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
219f0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
21a00 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
21a10 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
21a20 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
21a30 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
21a40 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
21a50 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
21a60 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
21a70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
21a80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
21a90 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
21aa0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
21ab0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
21ac0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
21ad0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
21ae0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
21af0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
21b00 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
21b10 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
21b20 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
21b30 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a  cks {F16700}.**.
21b40 2a 2a 20 7b 46 31 36 37 30 31 7d 0a 2a 2a 20 54  ** {F16701}.** T
21b50 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
21b60 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
21b70 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
21b80 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
21b90 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
21ba0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
21bb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
21bc0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
21bd0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61  d with the.** da
21be0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f  tabase handle to
21bf0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65   be called whene
21c00 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
21c10 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
21c20 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72  nce is.** requir
21c30 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30  ed..**.** {F1670
21c40 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e  2}.** If the fun
21c50 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
21c60 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
21c70 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
21c80 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
21c90 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
21ca0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
21cb0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
21cc0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
21cd0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
21ce0 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46  ded in UTF-8. {F
21cf0 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65  16703} If sqlite
21d00 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
21d10 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 20  ed16() is used, 
21d20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65  the names.** are
21d30 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
21d40 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
21d50 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20  ive byte order. 
21d60 7b 46 31 36 37 30 34 7d 20 41 20 63 61 6c 6c 20  {F16704} A call 
21d70 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e  to either.** fun
21d80 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
21d90 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
21da0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  back..**.** {F16
21db0 37 30 35 7d 20 57 68 65 6e 20 74 68 65 20 63 61  705} When the ca
21dc0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21dd0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
21de0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
21df0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
21e00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
21e10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
21e20 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
21e30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
21e40 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
21e50 29 2e 20 7b 46 31 36 37 30 36 7d 20 54 68 65 20  ). {F16706} The 
21e60 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
21e70 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
21e80 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 7b 46 31 36  ** handle.  {F16
21e90 37 30 37 7d 20 54 68 65 20 74 68 69 72 64 20 61  707} The third a
21ea0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
21eb0 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
21ec0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
21ed0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
21ee0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
21ef0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a 2a  ating the most.*
21f00 2a 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  * desirable form
21f10 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
21f20 6e 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  n sequence funct
21f30 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ion required..**
21f40 20 7b 46 31 36 37 30 38 7d 20 54 68 65 20 66 6f   {F16708} The fo
21f50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
21f60 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21f70 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
21f80 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
21f90 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
21fa0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
21fb0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
21fc0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
21fd0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
21fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
21ff0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
22000 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
22010 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
22020 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
22030 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
22040 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
22050 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
22060 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
22070 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
22080 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
22090 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
220a0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
220b0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
220c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
220d0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
220e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
220f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
22100 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
22110 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
22120 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
22130 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
22140 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
22150 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
22160 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
22170 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
22180 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
22190 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
221a0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
221b0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
221c0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
221d0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
221e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
221f0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
22200 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
22210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22220 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
22230 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
22240 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
22250 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
22260 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
22270 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
22280 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
22290 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
222a0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
222b0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
222c0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
222d0 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
222e0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
222f0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
22300 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
22310 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
22320 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
22330 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
22340 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
22350 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
22360 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
22370 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
22380 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
22390 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
223a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
223b0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
223c0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
223d0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
223e0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
223f0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
22400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22410 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  :  Suspend Execu
22420 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
22430 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a   Time {F10530}.*
22440 2a 0a 2a 2a 20 7b 46 31 30 35 33 31 7d 20 54 68  *.** {F10531} Th
22450 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
22460 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  ) function.** ca
22470 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
22480 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
22490 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
224a0 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
224b0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
224c0 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
224d0 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
224e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 32 7d  ..**.** {F10532}
224f0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
22500 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
22510 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
22520 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a  requests with .*
22530 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
22540 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
22550 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
22560 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
22570 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65  to .** the neare
22580 73 74 20 73 65 63 6f 6e 64 2e 20 7b 46 31 30 35  st second. {F105
22590 33 33 7d 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  33} The number o
225a0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
225b0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
225c0 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66   .** requested f
225d0 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
225e0 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
225f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  rned..**.** {F10
22600 35 33 34 7d 20 53 51 4c 69 74 65 20 69 6d 70 6c  534} SQLite impl
22610 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
22620 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
22630 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
22640 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
22650 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
22660 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e  vfs] object. {EN
22670 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D}.*/.int sqlite
22680 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
22690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
226a0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
226b0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
226c0 72 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33  rary Files {F103
226d0 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69  10}.**.** If thi
226e0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
226f0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
22700 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
22710 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
22720 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
22730 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72 79  (a.ka. directory
22740 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
22750 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
22760 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
22770 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
22780 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
22790 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69  y.  If this vari
227a0 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20  able.** is NULL 
227b0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
227c0 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61 72  Lite does a sear
227d0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
227e0 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a  riate temporary.
227f0 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ** file director
22800 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
22810 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66  ot safe to modif
22820 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
22830 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65 20  once a database 
22840 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61  connection.** ha
22850 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20  s been opened.  
22860 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
22870 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
22880 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
22890 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
228a0 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
228b0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
228c0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
228d0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
228e0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e  ave been call an
228f0 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  d remain unchang
22900 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ed thereafter..*
22910 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
22920 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
22930 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
22940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
22950 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
22960 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20 49  he Database Is I
22970 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  n Auto-Commit Mo
22980 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a  de {F12930}.**.*
22990 2a 20 7b 46 31 32 39 33 31 7d 20 54 68 65 20 73  * {F12931} The s
229a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
229b0 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
229c0 65 73 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  es returns non-z
229d0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
229e0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
229f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22a00 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
22a10 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
22a20 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
22a30 2e 20 7b 46 31 32 39 33 32 7d 20 20 41 75 74 6f  . {F12932}  Auto
22a40 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
22a50 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e  n.** by default.
22a60 20 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63    {F12933} Autoc
22a70 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
22a80 73 61 62 6c 65 64 20 62 79 20 61 20 42 45 47 49  sabled by a BEGI
22a90 4e 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  N statement..** 
22aa0 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d  {F12934} Autocom
22ab0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 65 6e  mit mode is reen
22ac0 61 62 6c 65 64 20 62 79 20 61 20 43 4f 4d 4d 49  abled by a COMMI
22ad0 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 20 7b  T or ROLLBACK. {
22ae0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  END}.**.** If ce
22af0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
22b00 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
22b10 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
22b20 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
22b30 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
22b40 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ons (errors incl
22b50 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
22b60 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
22b70 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  RR], .** [SQLITE
22b80 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
22b90 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
22ba0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
22bb0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
22bc0 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
22bd0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
22be0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 7b 46 31  omatically.  {F1
22bf0 32 39 33 35 7d 20 54 68 65 20 6f 6e 6c 79 20 77  2935} The only w
22c00 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
22c10 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f  t if SQLite auto
22c20 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
22c30 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
22c40 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
22c50 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
22c60 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
22c70 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 55 31   {END}.**.** {U1
22c80 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72  2936} If another
22c90 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
22ca0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
22cb0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
22cc0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
22cd0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
22ce0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
22cf0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
22d00 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
22d10 6e 64 65 66 69 6e 65 64 2e 20 7b 45 4e 44 7d 0a  ndefined. {END}.
22d20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
22d30 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
22d40 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
22d50 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20  CAPI3REF:  Find 
22d60 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
22d70 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
22d80 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
22d90 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  120}.**.** {F131
22da0 32 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  21} The sqlite3_
22db0 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
22dc0 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
22dd0 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
22de0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f  tabase handle to
22df0 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73 71 6c   which a.** [sql
22e00 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
22e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22e20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 7b 46 31 33  belongs..** {F13
22e30 31 32 32 7d 20 74 68 65 20 64 61 74 61 62 61 73  122} the databas
22e40 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65  e handle returne
22e50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
22e60 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65  handle.** is the
22e70 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68   same database h
22e80 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a  andle that was.*
22e90 2a 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  * the first argu
22ea0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
22eb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22ec0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
22ed0 74 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75  ts.** that was u
22ee0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 74 68  sed to create th
22ef0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
22f00 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
22f10 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
22f20 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
22f30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a  lite3_stmt*);...
22f40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22f50 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
22f60 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
22f70 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
22f80 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  50}.**.** {F1295
22f90 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  1} The sqlite3_c
22fa0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
22fb0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
22fc0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
22fd0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
22fe0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
22ff0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
23000 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 7b 46  committed..** {F
23010 31 32 39 35 32 7d 20 41 6e 79 20 63 61 6c 6c 62  12952} Any callb
23020 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
23030 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
23040 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
23050 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
23060 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
23070 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
23080 69 64 64 65 6e 2e 0a 2a 2a 20 7b 46 31 32 39 35  idden..** {F1295
23090 33 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  3} The sqlite3_r
230a0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
230b0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
230c0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
230d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
230e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
230f0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
23100 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
23110 7b 46 31 32 39 35 34 7d 20 41 6e 79 20 63 61 6c  {F12954} Any cal
23120 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
23130 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
23140 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
23150 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
23160 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
23170 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
23180 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 7b 46 31 32  rridden..** {F12
23190 39 35 36 7d 20 54 68 65 20 70 41 72 67 20 61 72  956} The pArg ar
231a0 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
231b0 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74   through.** to t
231c0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 7b 46  he callback.  {F
231d0 31 32 39 35 37 7d 20 49 66 20 74 68 65 20 63 61  12957} If the ca
231e0 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
231f0 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
23200 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e   .** returns non
23210 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
23220 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
23230 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
23240 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
23250 35 38 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 66  58} If another f
23260 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
23270 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
23280 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76  d, its.** pArg v
23290 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
232a0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
232b0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
232c0 2a 0a 2a 2a 20 7b 46 31 32 39 35 39 7d 20 52 65  *.** {F12959} Re
232d0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
232e0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
232f0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
23300 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20  .**.** {F12961} 
23310 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
23320 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
23330 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
23340 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
23350 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b   .** rolled back
23360 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
23370 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
23380 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
23390 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
233a0 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
233b0 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
233c0 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
233d0 63 75 72 2e 0a 2a 2a 20 7b 46 31 32 39 36 32 7d  cur..** {F12962}
233e0 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
233f0 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
23400 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
23410 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
23420 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
23430 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
23440 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23450 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
23460 2e 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20 54 68  ..** {F12964} Th
23470 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
23480 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
23490 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
234a0 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
234b0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
234c0 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
234d0 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
234e0 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
234f0 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
23500 6f 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  o> {END}.**.** T
23510 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d  hese are experim
23520 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
23530 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74   and are subject
23540 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76   to change..*/.v
23550 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
23560 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
23570 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
23580 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
23590 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
235a0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
235b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
235c0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
235d0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
235e0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
235f0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
23600 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2970}.**.** {F12
23610 39 37 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  971} The sqlite3
23620 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
23630 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67 69  nterface.** regi
23640 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
23650 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
23660 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23670 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65  ection identifie
23680 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72  d by the .** fir
23690 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62  st argument to b
236a0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
236b0 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
236c0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
236d0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 7b 46 31   deleted..** {F1
236e0 32 39 37 32 7d 20 41 6e 79 20 63 61 6c 6c 62 61  2972} Any callba
236f0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
23700 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
23710 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74  s function for t
23720 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61  he same .** data
23730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23740 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
23750 2a 0a 2a 2a 20 7b 46 31 32 39 37 34 7d 20 54 68  *.** {F12974} Th
23760 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
23770 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23780 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
23790 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20  o invoke when a 
237a0 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
237b0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
237c0 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 7b 46 31  deleted. .** {F1
237d0 32 39 37 36 7d 20 54 68 65 20 66 69 72 73 74 20  2976} The first 
237e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
237f0 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61  callback is.** a
23800 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
23810 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
23820 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
23830 6f 6b 28 29 2e 0a 2a 2a 20 7b 46 31 32 39 37 37  ok()..** {F12977
23840 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c  } The second cal
23850 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65  lback .** argume
23860 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
23870 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
23880 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
23890 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
238a0 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
238b0 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
238c0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
238d0 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
238e0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 7b 46 31 32 39  nvoked..** {F129
238f0 37 38 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e  78} The third an
23900 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67  d .** fourth arg
23910 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
23920 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
23930 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64  ointers to the d
23940 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20  atabase and .** 
23950 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
23960 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
23970 65 64 20 72 6f 77 2e 0a 2a 2a 20 7b 46 31 32 39  ed row..** {F129
23980 37 39 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61  79} The final ca
23990 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
239a0 20 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69   is .** the rowi
239b0 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  d of the row..**
239c0 20 7b 46 31 32 39 38 31 7d 20 49 6e 20 74 68 65   {F12981} In the
239d0 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61   case of an upda
239e0 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
239f0 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20  rowid after .** 
23a00 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
23a10 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   place..**.** {F
23a20 31 32 39 38 33 7d 20 54 68 65 20 75 70 64 61 74  12983} The updat
23a30 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
23a40 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
23a50 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
23a60 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
23a70 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
23a80 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
23a90 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
23aa0 2a 20 7b 46 31 32 39 38 34 7d 20 49 66 20 61 6e  * {F12984} If an
23ab0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
23ac0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
23ad0 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
23ae0 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72  rg value.** is r
23af0 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 32 39 38  eturned.  {F1298
23b00 35 7d 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  5} Otherwise NUL
23b10 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
23b20 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
23b30 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
23b40 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
23b50 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
23b60 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
23b70 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
23b80 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
23b90 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
23ba0 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
23bb0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
23bc0 50 61 67 65 72 20 43 61 63 68 65 20 7b 46 31 30  Pager Cache {F10
23bd0 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33  330}.**.** {F103
23be0 33 31 7d 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  31}.** This rout
23bf0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
23c00 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
23c10 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
23c20 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
23c30 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
23c40 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
23c50 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74  connections to t
23c60 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
23c70 2e 0a 2a 2a 20 7b 46 31 30 33 33 32 7d 0a 2a 2a  ..** {F10332}.**
23c80 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
23c90 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
23ca0 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20  ent is true and 
23cb0 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
23cc0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66  argument.** is f
23cd0 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  alse..**.** {F10
23ce0 33 33 33 7d 20 43 61 63 68 65 20 73 68 61 72 69  333} Cache shari
23cf0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
23d00 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f  d disabled.** fo
23d10 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
23d20 65 73 73 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20  ess. {END} This 
23d30 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
23d40 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
23d50 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72   3.5.0..** In pr
23d60 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
23d70 53 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20  SQLite, sharing 
23d80 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
23d90 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
23da0 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
23db0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ately..**.** {F1
23dc0 30 33 33 34 7d 0a 2a 2a 20 54 68 65 20 63 61 63  0334}.** The cac
23dd0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
23de0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
23df0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
23e00 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
23e10 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
23e20 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
23e30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
23e40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
23e50 6e 31 36 28 29 5d 2e 0a 2a 2a 20 7b 46 31 30 33  n16()]..** {F103
23e60 33 35 7d 20 45 78 69 73 74 69 6e 67 20 64 61 74  35} Existing dat
23e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23e80 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
23e90 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
23ea0 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
23eb0 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
23ec0 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
23ed0 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ed. {END}.**.** 
23ee0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
23ef0 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69  annot be used wi
23f00 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68  th a shared cach
23f10 65 2e 20 20 7b 46 31 30 33 33 36 7d 20 57 68 65  e.  {F10336} Whe
23f20 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
23f30 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
23f40 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
23f50 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20  e_module()] API 
23f60 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
23f70 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
23f80 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  es will always r
23f90 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20  eturn an error. 
23fa0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  {END}.**.** {F10
23fb0 33 33 37 7d 20 54 68 69 73 20 72 6f 75 74 69 6e  337} This routin
23fc0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
23fd0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
23fe0 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61  cache was.** ena
23ff0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
24000 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
24010 7b 46 31 30 33 33 38 7d 20 41 6e 20 5b 53 51 4c  {F10338} An [SQL
24020 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f  ITE_ERROR | erro
24030 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65  r code].** is re
24040 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
24050 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
24060 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61  10339} Shared ca
24070 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
24080 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45 4e 44  by default. {END
24090 7d 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  } But this might
240a0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
240b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
240c0 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
240d0 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
240e0 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
240f0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
24100 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
24110 6c 69 63 69 74 6c 79 2e 0a 2a 2f 0a 69 6e 74 20  licitly..*/.int 
24120 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
24130 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29  hared_cache(int)
24140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24150 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46  F:  Attempt To F
24160 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20  ree Heap Memory 
24170 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F17340}.**.** {
24180 46 31 37 33 34 31 7d 20 54 68 65 20 73 71 6c 69  F17341} The sqli
24190 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
241a0 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
241b0 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72  ttempts to.** fr
241c0 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65  ee N bytes of he
241d0 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
241e0 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
241f0 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a  sential memory.*
24200 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65  * allocations he
24210 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
24220 73 65 20 6c 61 62 72 61 72 79 2e 20 7b 45 4e 44  se labrary. {END
24230 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a  }  Memory used.*
24240 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  * to cache datab
24250 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70  ase pages to imp
24260 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
24270 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
24280 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  f.** non-essenti
24290 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 7b 46 31 36  al memory.  {F16
242a0 33 34 32 7d 20 73 71 6c 69 74 65 33 5f 72 65 6c  342} sqlite3_rel
242b0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
242c0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
242d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
242e0 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69  ually freed, whi
242f0 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
24300 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e   or less.** than
24310 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
24320 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ested..*/.int sq
24330 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
24340 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
24350 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70  * CAPI3REF:  Imp
24360 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
24370 65 61 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30  eap Size {F17350
24380 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d  }.**.** {F16351}
24390 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66   The sqlite3_sof
243a0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69  t_heap_limit() i
243b0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63  nterface.** plac
243c0 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  es a "soft" limi
243d0 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
243e0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
243f0 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
24400 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74  ated.** by SQLit
24410 65 2e 20 7b 46 31 36 33 35 32 7d 20 49 66 20 61  e. {F16352} If a
24420 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63  n internal alloc
24430 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
24440 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c  ed .** that woul
24450 64 20 65 78 63 65 65 64 20 74 68 65 20 73 6f 66  d exceed the sof
24460 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
24470 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
24480 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69  emory()] is.** i
24490 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  nvoked one or mo
244a0 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
244b0 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
244c0 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
244d0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e  tion.** is made.
244e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
244f0 36 33 35 33 7d 20 54 68 65 20 6c 69 6d 69 74 20  6353} The limit 
24500 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
24510 2c 20 62 65 63 61 75 73 65 20 69 66 0a 2a 2a 20  , because if.** 
24520 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
24530 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f  _memory()] canno
24540 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63  t.** free suffic
24550 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
24560 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
24570 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
24580 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
24590 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
245a0 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
245b0 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
245c0 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
245d0 2a 20 7b 46 31 36 33 35 34 7d 0a 2a 2a 20 41 20  * {F16354}.** A 
245e0 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
245f0 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
24600 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
24610 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
24620 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
24630 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
24640 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
24650 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
24660 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
24670 65 64 2e 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20  ed..** {F16355} 
24680 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
24690 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
246a0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
246b0 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  o..**.** SQLite 
246c0 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
246d0 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
246e0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
246f0 2e 20 20 0a 2a 2a 20 7b 46 31 36 33 35 36 7d 20  .  .** {F16356} 
24700 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
24710 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
24720 74 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75  t honored, execu
24730 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
24740 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
24750 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
24760 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73  ion. {END}  This
24770 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
24780 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20  t is .** called 
24790 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
247a0 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
247b0 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
247c0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
247d0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
247e0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
247f0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
24800 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
24810 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
24820 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
24830 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
24840 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
24850 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
24860 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
24870 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
24880 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
24890 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
248a0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 46 31  all threads. {F1
248b0 36 33 35 37 7d 20 54 68 65 20 76 61 6c 75 65 20  6357} The value 
248c0 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68  specified for th
248d0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
248e0 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72  t.** is an upper
248f0 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f   bound on the to
24900 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tal memory alloc
24910 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68  ation for all th
24920 72 65 61 64 73 2e 20 7b 45 4e 44 7d 20 20 49 6e  reads. {END}  In
24930 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
24940 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
24950 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
24960 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
24970 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
24980 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
24990 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
249a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
249b0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
249c0 33 52 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d  3REF:  Extract M
249d0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
249e0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
249f0 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a  e {F12850}.**.**
24a00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   This routine.**
24a10 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61   returns meta-da
24a20 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
24a30 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
24a40 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73  specific databas
24a50 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73  e.** table acces
24a60 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
24a70 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  connection handl
24a80 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
24a90 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a  first function .
24aa0 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ** argument..**.
24ab0 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  ** The column is
24ac0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
24ad0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
24ae0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
24af0 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68  meters to .** th
24b00 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  is function. The
24b10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24b20 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
24b30 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24b40 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
24b50 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20  ain", "temp" or 
24b60 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
24b70 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
24b80 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
24b90 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
24ba0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
24bb0 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
24bc0 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
24bd0 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
24be0 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
24bf0 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
24c00 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61  hm as the databa
24c10 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74  se engine uses t
24c20 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  o .** resolve un
24c30 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
24c40 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
24c50 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  * The third and 
24c60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
24c70 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
24c80 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
24c90 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20   and column .** 
24ca0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
24cb0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
24cc0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
24cd0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
24ce0 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65  eters .** may be
24cf0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74   NULL..**.** Met
24d00 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  a information is
24d10 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
24d20 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
24d30 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
24d40 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74  sed as.** the 5t
24d50 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  h and subsequent
24d60 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
24d70 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e  his function. An
24d80 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61  y of these .** a
24d90 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20  rguments may be 
24da0 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
24db0 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
24dc0 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
24dd0 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d   meta .** inform
24de0 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65  ation is ommitte
24df0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  d..**.** <pre>.*
24e00 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20  * Parameter     
24e10 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20  Output Type     
24e20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   Description.** 
24e30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
24e40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
24e50 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20  ---.**.**   5th 
24e60 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68          const ch
24e70 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79  ar*      Data ty
24e80 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20  pe.**   6th     
24e90 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
24ea0 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65       Name of the
24eb0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
24ec0 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20  on sequence .** 
24ed0 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e    7th         in
24ee0 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
24ef0 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
24f00 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
24f10 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20   constraint.**  
24f20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   8th         int
24f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
24f40 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
24f50 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
24f60 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20  PRIMARY KEY.**  
24f70 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   9th         int
24f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
24f90 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
24fa0 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e   is AUTOINCREMEN
24fb0 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  T.** </pre>.**.*
24fc0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
24fd0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
24fe0 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
24ff0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
25000 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72  r the .** declar
25010 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
25020 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
25030 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
25040 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a  until the next .
25050 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73  ** call to any s
25060 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  qlite API functi
25070 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
25080 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
25090 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
250a0 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72  iew, then an err
250b0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
250c0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
250d0 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73  cified column is
250e0 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20   "rowid", "oid" 
250f0 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64  or "_rowid_" and
25100 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20   an .** INTEGER 
25110 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75  PRIMARY KEY colu
25120 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
25130 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
25140 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
25150 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20   .** parameters 
25160 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
25170 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
25180 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74  red column. If t
25190 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
251a0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
251b0 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68  d IPK column, th
251c0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61  en the output pa
251d0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
251e0 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a   as .** follows:
251f0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
25200 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
25210 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
25220 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
25230 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
25240 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
25250 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
25260 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
25270 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
25280 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54  * </pre>.**.** T
25290 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
252a0 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
252b0 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
252c0 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
252d0 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
252e0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
252f0 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
25300 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
25310 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
25320 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
25330 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f  , an SQLITE erro
25340 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
25350 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
25360 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20  message.** left 
25370 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
25380 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65  handle (to be re
25390 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
253a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
253b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
253c0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
253d0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
253e0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
253f0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
25400 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
25410 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
25420 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
25430 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
25440 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
25450 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
25460 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
25470 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
25480 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
25490 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
254a0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
254b0 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
254c0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
254d0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
254e0 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
254f0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
25500 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
25510 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
25520 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
25530 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
25540 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
25550 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
25560 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
25570 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
25580 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
25590 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
255a0 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
255b0 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
255c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
255d0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
255e0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
255f0 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
25600 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
25610 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
25620 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
25630 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
25640 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
25650 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
25660 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
25670 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
25680 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
25690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
256a0 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
256b0 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a  sion {F12600}.**
256c0 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65  .** {F12601} The
256d0 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
256e0 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
256f0 61 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20  ace.** attempts 
25700 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74  to load an SQLit
25710 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
25720 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e  ary contained in
25730 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69   the file.** zFi
25740 6c 65 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65  le. {F12602} The
25750 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
25760 7a 50 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20  zProc. {F12603} 
25770 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a  zProc may be 0.*
25780 2a 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  * in which case 
25790 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
257a0 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61  entry point defa
257b0 75 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69  ults.** to "sqli
257c0 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
257d0 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  it"..**.** {F126
257e0 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  04} The sqlite3_
257f0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
25800 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
25810 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
25820 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
25830 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
25840 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
25850 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
25860 0a 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20  .** {F12605}.** 
25870 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
25880 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20  rs and pzErrMsg 
25890 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74  is not 0, then t
258a0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f  he.** sqlite3_lo
258b0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
258c0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
258d0 74 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a  ttempt to fill *
258e0 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a  pzErrMsg with .*
258f0 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * error message 
25900 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d  text stored in m
25910 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
25920 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
25930 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d  loc()]..** {END}
25940 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
25950 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72  nction should fr
25960 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a  ee this memory.*
25970 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  * by calling [sq
25980 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
25990 2a 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a  *.** {F12606}.**
259a0 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   Extension loadi
259b0 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c  ng must be enabl
259c0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
259d0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
259e0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72  tension()].** pr
259f0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74  ior to calling t
25a00 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72  his API or an er
25a10 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ror will be retu
25a20 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
25a30 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
25a40 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
25a50 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
25a60 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69  Load the extensi
25a70 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74  on into this dat
25a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25a90 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
25aa0 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e   *zFile,    /* N
25ab0 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65  ame of the share
25ac0 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  d library contai
25ad0 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a  ning extension *
25ae0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25af0 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74  zProc,    /* Ent
25b00 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76  ry point.  Deriv
25b10 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66  ed from zFile if
25b20 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70   0 */.  char **p
25b30 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a  zErrMsg       /*
25b40 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61   Put error messa
25b50 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30  ge here if not 0
25b60 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
25b70 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20  PI3REF:  Enable 
25b80 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
25b90 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31  sion Loading {F1
25ba0 32 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61  2620}.**.** So a
25bb0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
25bc0 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
25bd0 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
25be0 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
25bf0 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
25c00 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
25c10 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
25c20 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
25c30 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
25c40 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
25c50 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
25c60 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
25c70 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41  e following.** A
25c80 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  PI is provided t
25c90 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
25ca0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
25cb0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
25cc0 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20  on and.** off.  
25cd0 7b 46 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f  {F12622} It is o
25ce0 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b  ff by default. {
25cf0 45 4e 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20  END} See ticket 
25d00 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  #1863..**.** {F1
25d10 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73  2621} Call the s
25d20 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
25d30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
25d40 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f  outine.** with o
25d50 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20  noff==1 to turn 
25d60 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
25d70 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c  g on.** and call
25d80 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d   it with onoff==
25d90 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63  0 to turn it bac
25da0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e  k off again. {EN
25db0 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D}.*/.int sqlite
25dc0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
25dd0 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
25de0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
25df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25e00 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65  : Make Arrangeme
25e10 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63  nts To Automatic
25e20 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
25e30 65 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a  ension {F12640}.
25e40 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54  **.** {F12641} T
25e50 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
25e60 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74  registers an ext
25e70 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69  ension entry poi
25e80 6e 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d  nt that is autom
25e90 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
25ea0 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e  .** whenever a n
25eb0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
25ec0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
25ed0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
25ee0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
25ef0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
25f00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
25f10 5f 76 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a  _v2()]. {END}.**
25f20 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e  .** This API can
25f30 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70   be invoked at p
25f40 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69  rogram startup i
25f50 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73  n order to regis
25f60 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
25f70 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69  re statically li
25f80 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20  nked extensions 
25f90 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61  that will be ava
25fa0 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c  ilable.** to all
25fb0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
25fc0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
25fd0 20 7b 46 31 32 36 34 32 7d 20 44 75 70 6c 69 63   {F12642} Duplic
25fe0 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
25ff0 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
26000 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
26010 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ine multiple.** 
26020 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
26030 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
26040 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a   harmless..**.**
26050 20 7b 46 31 32 36 34 33 7d 20 54 68 69 73 20 72   {F12643} This r
26060 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
26070 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
26080 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61  xtension in an a
26090 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20  rray.** that is 
260a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
260b0 6c 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b  lite_malloc(). {
260c0 45 4e 44 7d 20 49 66 20 79 6f 75 20 72 75 6e 20  END} If you run 
260d0 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a  a memory leak.**
260e0 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72   checker on your
260f0 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20   program and it 
26100 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62  reports a leak b
26110 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
26120 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e  * array, then in
26130 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  voke [sqlite3_re
26140 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
26150 6f 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74  on()] prior.** t
26160 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72  o shutdown to fr
26170 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a  ee the memory..*
26180 2a 0a 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41 75  *.** {F12644} Au
26190 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
261a0 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20  ns apply across 
261b0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e  all threads. {EN
261c0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  D}.**.** This in
261d0 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
261e0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
261f0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
26200 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
26210 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
26220 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
26230 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
26240 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
26250 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a  *xEntryPoint);..
26260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26270 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
26280 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
26290 6e 67 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a  ng {F12660}.**.*
262a0 2a 20 7b 46 31 32 36 36 31 7d 20 54 68 69 73 20  * {F12661} This 
262b0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
262c0 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  s all previously
262d0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 61   registered.** a
262e0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
262f0 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73  ons. {END}  This
26300 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
26310 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
26320 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69   all prior [sqli
26330 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78  te3_automatic_ex
26340 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61  tension()].** ca
26350 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  lls..**.** {F126
26360 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20 64 69  62} This call di
26370 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  sabled automatic
26380 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
26390 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44  ll threads. {END
263a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
263b0 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
263c0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
263d0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
263e0 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
263f0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
26400 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
26410 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
26420 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
26430 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a  (void);.../*.***
26440 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
26450 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
26460 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
26470 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
26480 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
26490 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
264a0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
264b0 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
264c0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
264d0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
264e0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
264f0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
26500 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
26510 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
26520 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
26530 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
26540 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
26550 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
26560 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
26570 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
26580 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c  anism stablizes,
26590 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
265a0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
265b0 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
265c0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
265d0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
265e0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
265f0 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
26600 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
26610 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
26620 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
26630 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
26640 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
26650 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
26660 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
26670 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
26680 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
26690 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
266a0 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
266b0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
266c0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
266d0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
266e0 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
266f0 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20  .** A module is 
26700 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75  a class of virtu
26710 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68  al tables.  Each
26720 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e   module is defin
26730 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74  ed.** by an inst
26740 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c  ance of the foll
26750 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e  owing structure.
26760 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65    This structure
26770 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73   consists.** mos
26780 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66  tly of methods f
26790 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
267a0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
267b0 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
267c0 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
267d0 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
267e0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
267f0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
26800 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
26810 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
26820 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
26830 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
26840 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
26850 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
26860 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
26870 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
26880 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
26890 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
268a0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
268b0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
268c0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
268d0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
268e0 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
268f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
26900 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
26910 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
26920 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
26930 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
26940 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
26950 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
26960 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
26970 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
26980 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
26990 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
269a0 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
269b0 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
269c0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
269d0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
269e0 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
269f0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
26a00 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
26a10 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
26a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
26a30 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
26a40 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
26a50 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
26a60 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
26a70 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
26a80 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
26a90 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
26aa0 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
26ab0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
26ac0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26ad0 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
26ae0 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
26af0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
26b00 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
26b10 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
26b20 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
26b30 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
26b40 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
26b50 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
26b60 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
26b70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
26b80 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
26b90 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
26ba0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
26bb0 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
26bc0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
26bd0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
26be0 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
26bf0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
26c00 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
26c10 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
26c20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
26c30 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
26c40 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
26c50 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
26c60 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
26c70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26c80 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26c90 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
26ca0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
26cb0 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20  *ppArg);..  int 
26cc0 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
26cd0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
26ce0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
26cf0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  );.};../*.** The
26d00 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
26d10 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
26d20 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
26d30 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
26d40 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
26d50 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
26d60 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
26d70 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  om the xBestInde
26d80 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  x.** method of a
26d90 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  n sqlite3_module
26da0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
26db0 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
26dc0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
26dd0 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
26de0 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
26df0 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
26e00 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
26e10 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
26e20 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
26e30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ..**.** The aCon
26e40 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
26e50 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
26e60 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
26e70 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a   of the.** form:
26e80 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63  .**.**         c
26e90 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a  olumn OP expr.**
26ea0 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20  .** Where OP is 
26eb0 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
26ec0 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20  &gt;, or &gt;=. 
26ed0 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75   .** The particu
26ee0 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20  lar operator is 
26ef0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f  stored.** in aCo
26f00 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20  nstraint[].op.  
26f10 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
26f20 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
26f30 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72  d in .** aConstr
26f40 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20  aint[].iColumn. 
26f50 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75   aConstraint[].u
26f60 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
26f70 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
26f80 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
26f90 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
26fa0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
26fb0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
26fc0 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
26fd0 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
26fe0 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70  ot..**.** The op
26ff0 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
27000 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
27010 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
27020 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
27030 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
27040 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
27050 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
27060 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
27070 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
27080 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
27090 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
270a0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
270b0 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
270c0 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  ..** The aConstr
270d0 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
270e0 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
270f0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20  clause terms in 
27100 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66  the correct.** f
27110 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74  orm that refer t
27120 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
27130 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
27140 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
27150 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** Information 
27160 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
27170 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
27180 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
27190 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20  ]..** Each term 
271a0 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
271b0 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
271c0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
271d0 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  use..**.** The x
271e0 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
271f0 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
27200 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
27210 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
27220 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
27230 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
27240 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
27250 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
27260 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
27270 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
27280 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
27290 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
272a0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
272b0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
272c0 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
272d0 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
272e0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
272f0 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
27300 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
27310 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
27320 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
27330 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
27340 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
27350 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
27360 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
27370 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
27380 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
27390 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
273a0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46  d passed into xF
273b0 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65  ilter..** sqlite
273c0 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64  3_free() is used
273d0 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
273e0 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  if needToFreeIdx
273f0 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
27400 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
27410 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
27420 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46  t output from xF
27430 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72  ilter will occur
27440 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
27450 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
27460 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
27470 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
27480 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
27490 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
274a0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
274b0 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
274c0 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
274d0 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
274e0 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
274f0 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
27500 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
27510 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
27520 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
27530 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
27540 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
27550 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
27560 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
27570 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
27580 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
27590 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
275a0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
275b0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
275c0 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
275d0 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
275e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
275f0 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
27600 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
27610 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
27620 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
27630 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
27640 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
27650 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
27660 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
27670 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
27680 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
27690 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
276a0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
276b0 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
276c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
276d0 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
276e0 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
276f0 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
27700 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
27710 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
27720 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
27730 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
27740 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
27750 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
27760 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
27770 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
27780 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
27790 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
277a0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
277b0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
277c0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
277d0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
277e0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
277f0 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
27800 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
27810 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
27820 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
27830 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
27840 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
27850 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
27860 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
27870 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
27880 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
27890 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
278a0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
278b0 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
278c0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
278d0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
278e0 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
278f0 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
27900 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
27910 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
27920 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
27930 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
27940 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
27950 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
27960 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
27970 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
27980 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
27990 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
279a0 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
279b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
279c0 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
279d0 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
279e0 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
279f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27a00 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
27a10 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
27a20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
27a30 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
27a40 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
27a50 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
27a60 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
27a70 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
27a80 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
27a90 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
27aa0 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
27ab0 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
27ac0 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
27ad0 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
27ae0 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
27af0 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
27b00 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
27b10 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
27b20 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
27b30 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
27b40 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
27b50 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
27b60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
27b70 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
27b80 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
27b90 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
27ba0 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
27bb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
27bc0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
27bd0 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
27be0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
27bf0 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
27c00 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  /*.** This routi
27c10 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
27c20 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
27c30 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e  ule name with an
27c40 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65   SQLite.** conne
27c50 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e  ction.  Module n
27c60 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
27c70 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63  istered before c
27c80 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76  reating new.** v
27c90 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e  irtual tables on
27ca0 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
27cb0 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65  before using pre
27cc0 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c  existing virtual
27cd0 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68  .** tables of th
27ce0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74  e module..*/.int
27cf0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27d00 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
27d10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
27d20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
27d30 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
27d40 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
27d50 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
27d60 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
27d70 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
27d80 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
27d90 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
27da0 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
27db0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
27dc0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20  e */.  void *   
27dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27de0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
27df0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
27e00 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
27e10 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
27e20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
27e30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
27e40 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68  te_module() meth
27e50 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63  od above,.** exc
27e60 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f  ept that it allo
27e70 77 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ws a destructor 
27e80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73  function to be s
27e90 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a  pecified. It is.
27ea0 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70  ** even more exp
27eb0 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74  erimental than t
27ec0 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76  he rest of the v
27ed0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50  irtual tables AP
27ee0 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  I..*/.int sqlite
27ef0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
27f00 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
27f10 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
27f20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
27f30 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
27f40 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
27f50 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
27f60 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
27f70 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
27f80 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
27f90 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c  qlite3_module *,
27fa0 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66      /* Methods f
27fb0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
27fc0 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
27fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27fe0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
27ff0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
28000 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
28010 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
28020 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
28030 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
28040 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 76 65  */.);../*.** Eve
28050 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
28060 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
28070 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
28080 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
28090 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
280a0 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  be a particular 
280b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
280c0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75  module.  Each su
280d0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
280e0 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
280f0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
28100 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
28110 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
28120 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20   The.** purpose 
28130 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
28140 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
28150 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
28160 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a  hat are common.*
28170 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  * to all module 
28180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
28190 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
281a0 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
281b0 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
281c0 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
281d0 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
281e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
281f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
28200 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
28210 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
28220 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
28230 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
28240 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
28250 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
28260 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20  free().** prior 
28270 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
28280 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
28290 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65  rMsg.  After the
282a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
282b0 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
282c0 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
282d0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
282e0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
282f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
28300 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
28310 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
28320 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
28330 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20  ill be zeroed.  
28340 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c  Note.** that sql
28350 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
28360 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  nd sqlite3_free(
28370 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68  ) are used on th
28380 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a  e zErrMsg field.
28390 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c  ** since virtual
283a0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d   tables are comm
283b0 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64  only implemented
283c0 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74   in loadable ext
283d0 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a  ensions which.**
283e0 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63   do not have acc
283f0 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50  ess to sqlite3MP
28400 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74  rintf() or sqlit
28410 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72  e3Free()..*/.str
28420 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
28430 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74   {.  const sqlit
28440 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
28450 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75  le;  /* The modu
28460 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74  le for this virt
28470 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69  ual table */.  i
28480 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20  nt nRef;        
28490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
284a0 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
284b0 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  y */.  char *zEr
284c0 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
284d0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
284e0 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
284f0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
28500 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
28510 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
28520 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
28530 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
28540 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
28550 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  ./* Every module
28560 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28570 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
28580 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
28590 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
285a0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
285b0 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
285c0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  o the virtual ta
285d0 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64  ble and are used
285e0 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f  .** to loop thro
285f0 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20  ugh the virtual 
28600 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20  table.  Cursors 
28610 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
28620 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d  g the.** xOpen m
28630 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
28640 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
28650 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
28660 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
28670 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
28680 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
28690 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
286a0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
286b0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
286c0 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
286d0 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
286e0 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
286f0 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
28700 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
28710 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
28720 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
28730 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
28740 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
28750 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
28760 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
28770 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
28780 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
28790 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
287a0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
287b0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
287c0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  */.};../*.** The
287d0 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f   xCreate and xCo
287e0 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66  nnect methods of
287f0 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68   a module use th
28800 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
28810 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
28820 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
28830 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
28840 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
28850 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
28860 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
28870 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e  implement..*/.in
28880 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
28890 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
288a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72   const char *zCr
288b0 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a  eateTable);../*.
288c0 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
288d0 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c  s can provide al
288e0 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d  ternative implem
288f0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e  entations of fun
28900 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20  ctions.** using 
28910 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f  the xFindFunctio
28920 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67  n method.  But g
28930 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
28940 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
28950 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
28960 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
28970 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a  verloaded..**.**
28980 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20   This API makes 
28990 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65  sure a global ve
289a0 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74  rsion of a funct
289b0 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69  ion with a parti
289c0 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e  cular.** name an
289d0 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  d number of para
289e0 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20  meters exists.  
289f0 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74  If no such funct
28a00 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65  ion exists.** be
28a10 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73  fore this API is
28a20 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66   called, a new f
28a30 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74  unction is creat
28a40 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  ed.  The impleme
28a50 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
28a60 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61  e new function a
28a70 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20  lways causes an 
28a80 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20  exception to be 
28a90 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74  thrown.  So.** t
28aa0 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
28ab0 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20  is not good for 
28ac0 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65  anything by itse
28ad0 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a  lf.  Its only.**
28ae0 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62   purpose is to b
28af0 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72  e a place-holder
28b00 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
28b10 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
28b20 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74  .** by virtual t
28b30 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ables..**.** Thi
28b40 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20  s API should be 
28b50 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20  considered part 
28b60 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
28b70 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a  able interface,.
28b80 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65  ** which is expe
28b90 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62  rimental and sub
28ba0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a  ject to change..
28bb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
28bc0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
28bd0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
28be0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
28bf0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
28c00 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
28c10 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
28c20 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
28c30 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
28c40 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
28c50 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
28c60 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
28c70 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
28c80 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
28c90 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
28ca0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
28cb0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
28cc0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
28cd0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
28ce0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
28cf0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
28d00 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
28d10 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
28d20 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
28d30 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
28d40 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
28d50 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
28d60 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
28d70 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
28d80 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
28d90 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
28da0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a  this comment..**
28db0 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
28dc0 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
28dd0 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
28de0 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
28df0 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ******.*/../*.**
28e00 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e   CAPI3REF: A Han
28e10 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42  dle To An Open B
28e20 4c 4f 42 20 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a  LOB {F17800}.**.
28e30 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
28e40 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
28e50 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
28e60 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20   is used to .** 
28e70 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f  represent an blo
28e80 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f  b-handle.  A blo
28e90 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61  b-handle is crea
28ea0 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
28eb0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
28ec0 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
28ed0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
28ee0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
28ef0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
28f00 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
28f10 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
28f20 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
28f30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
28f40 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
28f50 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
28f60 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
28f70 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
28f80 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
28f90 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
28fa0 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c  ize of the.** bl
28fb0 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  ob in bytes..*/.
28fc0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28fd0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
28fe0 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
28ff0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
29000 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
29010 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37 38  mental I/O {F178
29020 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31  10}.**.** {F1781
29030 31 7d 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  1} This interfac
29040 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64 6c  es opens a handl
29050 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f  e to the blob lo
29060 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20  cated.** in row 
29070 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a 43  iRow,, column zC
29080 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
29090 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
290a0 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
290b0 20 77 6f 72 64 73 2c 20 20 74 68 65 20 73 61 6d   words,  the sam
290c0 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c  e blob that woul
290d0 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79  d be selected by
290e0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
290f0 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c       SELECT zCol
29100 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61  umn FROM zDb.zTa
29110 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20  ble WHERE rowid 
29120 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65  = iRow;.** </pre
29130 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  > {END}.**.** {F
29140 31 37 38 31 32 7d 20 49 66 20 74 68 65 20 66 6c  17812} If the fl
29150 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
29160 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62   non-zero, the b
29170 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  lob is opened fo
29180 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77  r .** read and w
29190 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20  rite access. If 
291a0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
291b0 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66  blob is opened f
291c0 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65  or read .** acce
291d0 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ss. {END}.**.** 
291e0 7b 46 31 37 38 31 33 7d 20 4f 6e 20 73 75 63 63  {F17813} On succ
291f0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
29200 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
29210 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71   the new .** [sq
29220 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
29230 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  b handle] is wri
29240 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  tten to *ppBlob.
29250 20 0a 2a 2a 20 7b 46 31 37 38 31 34 7d 20 4f 74   .** {F17814} Ot
29260 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
29270 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
29280 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61  d and .** any va
29290 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a  lue written to *
292a0 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f  ppBlob should no
292b0 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65  t be used by the
292c0 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 7b 46 31 37   caller..** {F17
292d0 38 31 35 7d 20 54 68 69 73 20 66 75 6e 63 74 69  815} This functi
292e0 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61  on sets the data
292f0 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f  base-handle erro
29300 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
29310 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
29320 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
29330 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
29340 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
29350 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 65 20 73 68 6f  .** <todo>We sho
29360 75 6c 64 20 67 6f 20 74 68 72 6f 75 67 68 20 61  uld go through a
29370 6e 64 20 6d 61 72 6b 20 61 6c 6c 20 69 6e 74 65  nd mark all inte
29380 72 66 61 63 65 73 20 74 68 61 74 20 62 65 68 61  rfaces that beha
29390 76 65 20 74 68 69 73 0a 2a 2a 20 77 61 79 20 77  ve this.** way w
293a0 69 74 68 20 61 20 73 69 6d 69 6c 61 72 20 73 74  ith a similar st
293b0 61 74 65 6d 65 6e 74 3c 2f 74 6f 64 6f 3e 0a 2a  atement</todo>.*
293c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
293d0 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
293e0 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
293f0 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
29400 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
29410 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
29420 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
29430 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
29440 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
29450 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
29460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29470 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f  EF:  Close A BLO
29480 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 33 30  B Handle {F17830
29490 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e  }.**.** Close an
294a0 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62   open [sqlite3_b
294b0 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
294c0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33  e]..**.** {F1783
294d0 31 7d 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  1} Closing a BLO
294e0 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
294f0 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
29500 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
29510 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
29520 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
29530 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
29540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
29550 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
29560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29570 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  s in autocommit 
29580 6d 6f 64 65 2e 0a 2a 2a 20 7b 46 31 37 38 33 32  mode..** {F17832
29590 7d 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20  } If any writes 
295a0 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65  were made to the
295b0 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68   BLOB, they migh
295c0 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63  t be held in cac
295d0 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20  he.** until the 
295e0 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  close operation 
295f0 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74  if they will fit
29600 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73 69  . {END}.** Closi
29610 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65  ng the BLOB ofte
29620 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61  n forces the cha
29630 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64  nges.** out to d
29640 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e  isk and so if an
29650 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63  y I/O errors occ
29660 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69  ur, they will li
29670 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74  kely occur.** at
29680 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74   the time when t
29690 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65  he BLOB is close
296a0 64 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 6e 79  d.  {F17833} Any
296b0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
296c0 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f  ur during.** clo
296d0 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65  sing are reporte
296e0 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  d as a non-zero 
296f0 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a  return value..**
29700 0a 2a 2a 20 7b 46 31 37 38 33 39 7d 20 54 68 65  .** {F17839} The
29710 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
29720 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
29730 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
29740 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
29750 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
29760 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
29770 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e  ll closed..*/.in
29780 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
29790 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
297a0 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
297b0 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20 54  I3REF:  Return T
297c0 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
297d0 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 35 7d  en BLOB {F17805}
297e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 38 30 36 7d 20  .**.** {F16806} 
297f0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
29800 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20  in bytes of the 
29810 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20  blob accessible 
29820 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a  via the open .**
29830 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
29840 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61   blob-handle] pa
29850 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d  ssed as an argum
29860 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
29870 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
29880 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
29890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
298a0 20 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d    Read Data From
298b0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
298c0 74 61 6c 6c 79 20 7b 46 31 37 38 35 30 7d 0a 2a  tally {F17850}.*
298d0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
298e0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
298f0 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
29900 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
29910 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
29920 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c  ndle] into a cal
29930 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66  ler supplied buf
29940 66 65 72 2e 0a 2a 2a 20 7b 46 31 37 38 35 31 7d  fer..** {F17851}
29950 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
29960 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
29970 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f   buffer.** z fro
29980 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  m the open blob,
29990 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
299a0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
299b0 2a 2a 20 7b 46 31 37 38 35 32 7d 20 49 66 20 6f  ** {F17852} If o
299c0 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
299d0 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79 74   less than n byt
299e0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
299f0 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a  of the blob, .**
29a00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
29a10 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
29a20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
29a30 20 20 7b 46 31 37 38 35 33 7d 20 49 66 20 6e 20    {F17853} If n 
29a40 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
29a50 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
29a60 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
29a70 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
29a80 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  ead..**.** {F178
29a90 35 34 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  54} On success, 
29aa0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
29ab0 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65  urned. Otherwise
29ac0 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  , an .** [SQLITE
29ad0 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20  _ERROR | SQLite 
29ae0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
29af0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  n.** [SQLITE_IOE
29b00 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
29b10 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
29b20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69  s returned..*/.i
29b30 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
29b40 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f  read(sqlite3_blo
29b50 62 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  b *, void *z, in
29b60 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
29b70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29b80 45 46 3a 20 20 57 72 69 74 65 20 44 61 74 61 20  EF:  Write Data 
29b90 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72  Into A BLOB Incr
29ba0 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 37 38 37  ementally {F1787
29bb0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0}.**.** This fu
29bc0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
29bd0 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74  o write data int
29be0 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73  o an open .** [s
29bf0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
29c00 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20  ob-handle] from 
29c10 61 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  a user supplied 
29c20 62 75 66 66 65 72 2e 0a 2a 2a 20 7b 46 31 37 38  buffer..** {F178
29c30 37 31 7d 20 6e 20 62 79 74 65 73 20 6f 66 20 64  71} n bytes of d
29c40 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
29c50 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 0a 2a  rom the buffer.*
29c60 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
29c70 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20  z into the open 
29c80 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61  blob, starting a
29c90 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
29ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 32 7d  ..**.** {F17872}
29cb0 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
29cc0 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
29cd0 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74  dle] passed as t
29ce0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29cf0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70 65  t.** was not ope
29d00 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67 20  ned for writing 
29d10 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (the flags param
29d20 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
29d30 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
29d40 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68 69  * was zero), thi
29d50 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
29d60 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f  ns [SQLITE_READO
29d70 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  NLY]..**.** {F17
29d80 38 37 33 7d 20 54 68 69 73 20 66 75 6e 63 74 69  873} This functi
29d90 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
29da0 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
29db0 6f 66 20 74 68 65 20 62 6c 6f 62 3b 20 69 74 20  of the blob; it 
29dc0 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
29dd0 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
29de0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
29df0 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  b using this API
29e00 2e 0a 2a 2a 20 7b 46 31 37 38 37 34 7d 20 49 66  ..** {F17874} If
29e10 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
29e20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62  is less than n b
29e30 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
29e40 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a  d of the blob, .
29e50 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
29e60 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
29e70 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
29e80 74 74 65 6e 2e 20 20 7b 46 31 37 38 37 35 7d 20  tten.  {F17875} 
29e90 49 66 20 6e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  If n is.** less 
29ea0 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54  than zero [SQLIT
29eb0 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
29ec0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
29ed0 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a   is written..**.
29ee0 2a 2a 20 7b 46 31 37 38 37 36 7d 20 4f 6e 20 73  ** {F17876} On s
29ef0 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f  uccess, SQLITE_O
29f00 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f  K is returned. O
29f10 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a  therwise, an .**
29f20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
29f30 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f   SQLite error co
29f40 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  de] or an.** [SQ
29f50 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
29f60 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72  | extended error
29f70 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
29f80 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
29f90 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71  e3_blob_write(sq
29fa0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f  lite3_blob *, co
29fb0 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74  nst void *z, int
29fc0 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
29fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29fe0 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65  F:  Virtual File
29ff0 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20   System Objects 
2a000 7b 46 31 31 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F11200}.**.** A
2a010 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
2a020 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
2a030 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
2a040 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
2a050 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
2a060 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
2a070 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
2a080 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
2a090 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ost builds come 
2a0a0 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
2a0b0 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
2a0c0 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
2a0d0 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
2a0e0 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
2a0f0 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
2a100 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
2a110 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
2a120 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
2a130 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
2a140 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
2a150 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  rovided..**.** {
2a160 46 31 31 32 30 31 7d 20 54 68 65 20 73 71 6c 69  F11201} The sqli
2a170 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69  te3_vfs_find() i
2a180 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a190 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a   a pointer to .*
2a1a0 2a 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74  * a VFS given it
2a1b0 73 20 6e 61 6d 65 2e 20 20 7b 46 31 31 32 30 32  s name.  {F11202
2a1c0 7d 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65  } Names are case
2a1d0 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 7b   sensitive..** {
2a1e0 46 31 31 32 30 33 7d 20 4e 61 6d 65 73 20 61 72  F11203} Names ar
2a1f0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
2a200 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
2a210 0a 2a 2a 20 7b 46 31 31 32 30 34 7d 20 49 66 20  .** {F11204} If 
2a220 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63  there is no matc
2a230 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  h, a NULL.** poi
2a240 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2a250 2e 20 7b 46 31 31 32 30 35 7d 20 49 66 20 7a 56  . {F11205} If zV
2a260 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74  fsName is NULL t
2a270 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
2a280 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 74 75 72  .** VFS is retur
2a290 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ned. {END}.**.**
2a2a0 20 7b 46 31 31 32 31 30 7d 20 4e 65 77 20 56 46   {F11210} New VF
2a2b0 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
2a2c0 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
2a2d0 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
2a2e0 2a 2a 20 7b 46 31 31 32 31 31 7d 20 45 61 63 68  ** {F11211} Each
2a2f0 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73   new VFS becomes
2a300 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
2a310 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74   if the makeDflt
2a320 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a   flag is set..**
2a330 20 7b 46 31 31 32 31 32 7d 20 54 68 65 20 73 61   {F11212} The sa
2a340 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65  me VFS can be re
2a350 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
2a360 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20  e times without 
2a370 69 6e 6a 75 72 79 2e 0a 2a 2a 20 7b 46 31 31 32  injury..** {F112
2a380 31 33 7d 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65  13} To make an e
2a390 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f  xisting VFS into
2a3a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
2a3b0 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67  , register it ag
2a3c0 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ain.** with the 
2a3d0 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65  makeDflt flag se
2a3e0 74 2e 20 7b 55 31 31 32 31 34 7d 20 49 66 20 74  t. {U11214} If t
2a3f0 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53  wo different VFS
2a400 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73  es with the.** s
2a410 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67  ame name are reg
2a420 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68  istered, the beh
2a430 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2a440 65 64 2e 20 20 7b 55 31 31 32 31 35 7d 20 49 66  ed.  {U11215} If
2a450 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67   a.** VFS is reg
2a460 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e  istered with a n
2a470 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c  ame that is NULL
2a480 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
2a490 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ing,.** then the
2a4a0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2a4b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 7b  efined..** .** {
2a4c0 46 31 31 32 32 30 7d 20 55 6e 72 65 67 69 73 74  F11220} Unregist
2a4d0 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
2a4e0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
2a4f0 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
2a500 66 61 63 65 2e 0a 2a 2a 20 7b 46 31 31 32 32 31  face..** {F11221
2a510 7d 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74  } If the default
2a520 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74   VFS is unregist
2a530 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46  ered, another VF
2a540 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a  S is chosen as.*
2a550 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20  * the default.  
2a560 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74  The choice for t
2a570 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72  he new VFS is ar
2a580 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69  bitrary..*/.sqli
2a590 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33  te3_vfs *sqlite3
2a5a0 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20  _vfs_find(const 
2a5b0 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b  char *zVfsName);
2a5c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
2a5d0 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  _register(sqlite
2a5e0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65  3_vfs*, int make
2a5f0 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Dflt);.int sqlit
2a600 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
2a610 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b  r(sqlite3_vfs*);
2a620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a630 3a 20 4d 75 74 65 78 65 73 20 7b 46 31 37 30 30  : Mutexes {F1700
2a640 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0}.**.** The SQL
2a650 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
2a660 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2a670 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68   thread.** synch
2a680 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f  ronization.  Tho
2a690 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74  ugh they are int
2a6a0 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e  ended for intern
2a6b0 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
2a6c0 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c  ite, code that l
2a6d0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
2a6e0 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74  ite is.** permit
2a6f0 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f  ted to use any o
2a700 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2a710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ..**.** The SQLi
2a720 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63  te source code c
2a730 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65  ontains multiple
2a740 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2a750 20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75   .** of these mu
2a760 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41  tex routines.  A
2a770 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d  n appropriate im
2a780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
2a790 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f  is selected auto
2a7a0 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d  matically at com
2a7b0 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20  pile-time.  The 
2a7c0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70  following.** imp
2a7d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65  lementations are
2a7e0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2a7f0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a  e SQLite core:.*
2a800 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2a810 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
2a820 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _OS2.** <li>   S
2a830 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
2a840 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  EAD.** <li>   SQ
2a850 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a  LITE_MUTEX_W32.*
2a860 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
2a870 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f  MUTEX_NOOP.** </
2a880 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
2a890 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20  LITE_MUTEX_NOOP 
2a8a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
2a8b0 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69  s a set of routi
2a8c0 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f 65  nes .** that doe
2a8d0 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e  s no real lockin
2a8e0 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72  g and is appropr
2a8f0 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e 20  iate for use in 
2a900 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72  .** a single-thr
2a910 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
2a920 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  n.  The SQLITE_M
2a930 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c  UTEX_OS2,.** SQL
2a940 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41  ITE_MUTEX_PTHREA
2a950 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  D, and SQLITE_MU
2a960 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e  TEX_W32 implemen
2a970 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61  tations.** are a
2a980 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
2a990 73 65 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69 78  se on os/2, unix
2a9a0 2c 20 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a 2a  , and windows..*
2a9b0 2a 20 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20  * .** If SQLite 
2a9c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2a9d0 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   the SQLITE_MUTE
2a9e0 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63  X_APPDEF preproc
2a9f0 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64  essor.** macro d
2aa00 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44  efined (with "-D
2aa10 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50  SQLITE_MUTEX_APP
2aa20 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f  DEF=1"), then no
2aa30 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
2aa40 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c  entation is incl
2aa50 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  uded with the li
2aa60 62 72 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d  brary.  The.** m
2aa70 75 74 65 78 20 69 6e 74 65 72 66 61 63 65 20 72  utex interface r
2aa80 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
2aa90 68 65 72 65 20 62 65 63 6f 6d 65 20 65 78 74 65  here become exte
2aaa0 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e 63  rnal.** referenc
2aab0 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  es in the SQLite
2aac0 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68 69   library for whi
2aad0 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ch implementatio
2aae0 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70 72  ns.** must be pr
2aaf0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 61 70  ovided by the ap
2ab00 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  plication.  This
2ab10 20 66 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77 73   facility allows
2ab20 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69   an.** applicati
2ab30 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  on that links ag
2ab40 61 69 6e 73 74 20 53 51 4c 69 74 65 20 74 6f 20  ainst SQLite to 
2ab50 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20  provide its own 
2ab60 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
2ab70 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f 75 74 20  ntation without 
2ab80 68 61 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66 79  having to modify
2ab90 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
2aba0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 31 7d  ..**.** {F17011}
2abb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
2abc0 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
2abd0 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
2abe0 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
2abf0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2ac00 72 20 74 6f 20 69 74 2e 20 7b 46 31 37 30 31 32  r to it. {F17012
2ac10 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  } If it returns 
2ac20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
2ac30 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
2ac40 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
2ac50 6f 63 61 74 65 64 2e 20 7b 46 31 37 30 31 33 7d  ocated. {F17013}
2ac60 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
2ac70 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
2ac80 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
2ac90 72 72 6f 72 2e 20 7b 46 31 37 30 31 34 7d 20 54  rror. {F17014} T
2aca0 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
2acb0 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
2acc0 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f  alloc() is one o
2acd0 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
2ace0 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a  constants:.**.**
2acf0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
2ad00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
2ad10 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
2ad20 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
2ad30 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
2ad40 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
2ad50 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  STER.** <li>  SQ
2ad60 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
2ad70 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_MEM.** <li>  S
2ad80 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
2ad90 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20  IC_MEM2.** <li> 
2ada0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
2adb0 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69  ATIC_PRNG.** <li
2adc0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
2add0 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f  STATIC_LRU.** </
2ade0 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
2adf0 7b 46 31 37 30 31 35 7d 20 54 68 65 20 66 69 72  {F17015} The fir
2ae00 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  st two constants
2ae10 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d   cause sqlite3_m
2ae20 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20  utex_alloc() to 
2ae30 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20  create.** a new 
2ae40 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20  mutex.  The new 
2ae50 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
2ae60 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
2ae70 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
2ae80 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
2ae90 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
2aea0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
2aeb0 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
2aec0 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75   {END}.** The mu
2aed0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
2aee0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
2aef0 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69   to make a disti
2af00 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
2af10 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
2af20 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c  ECURSIVE and SQL
2af30 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
2af40 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  f it does.** not
2af50 20 77 61 6e 74 20 74 6f 2e 20 20 7b 46 31 37 30   want to.  {F170
2af60 31 36 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77  16} But SQLite w
2af70 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74  ill only request
2af80 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74   a recursive mut
2af90 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77  ex in.** cases w
2afa0 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e  here it really n
2afb0 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d  eeds one.  {END}
2afc0 20 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e   If a faster non
2afd0 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78  -recursive mutex
2afe0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2aff0 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
2b000 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74  on the host plat
2b010 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20  form, the mutex 
2b020 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67  subsystem.** mig
2b030 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61  ht return such a
2b040 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e   mutex in respon
2b050 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54  se to SQLITE_MUT
2b060 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b  EX_FAST..**.** {
2b070 46 31 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65  F17017} The othe
2b080 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65  r allowed parame
2b090 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  ters to sqlite3_
2b0a0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61  mutex_alloc() ea
2b0b0 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70  ch return.** a p
2b0c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74  ointer to a stat
2b0d0 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d  ic preexisting m
2b0e0 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75  utex. {END}  Fou
2b0f0 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  r static mutexes
2b100 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20   are.** used by 
2b110 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73  the current vers
2b120 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ion of SQLite.  
2b130 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
2b140 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79  of SQLite.** may
2b150 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
2b160 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20  static mutexes. 
2b170 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   Static mutexes 
2b180 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  are for internal
2b190 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
2b1a0 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61  e only.  Applica
2b1b0 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53  tions that use S
2b1c0 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68  QLite mutexes sh
2b1d0 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79  ould.** use only
2b1e0 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
2b1f0 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  exes returned by
2b200 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
2b210 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f  ST or.** SQLITE_
2b220 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e  MUTEX_RECURSIVE.
2b230 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 38 7d 20  .**.** {F17018} 
2b240 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65  Note that if one
2b250 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20   of the dynamic 
2b260 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73  mutex parameters
2b270 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46   (SQLITE_MUTEX_F
2b280 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45  AST.** or SQLITE
2b290 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
2b2a0 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73  ) is used then s
2b2b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
2b2c0 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  oc().** returns 
2b2d0 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65  a different mute
2b2e0 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e  x on every call.
2b2f0 20 20 7b 46 31 37 30 33 34 7d 20 42 75 74 20 66    {F17034} But f
2b300 6f 72 20 74 68 65 20 73 74 61 74 69 63 20 0a 2a  or the static .*
2b310 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
2b320 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
2b330 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
2b340 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
2b350 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
2b360 65 20 6e 75 6d 62 65 72 2e 20 7b 45 4e 44 7d 0a  e number. {END}.
2b370 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 39 7d 20 54  **.** {F17019} T
2b380 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
2b390 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
2b3a0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
2b3b0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
2b3c0 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
2b3d0 74 65 78 2e 20 7b 46 31 37 30 32 30 7d 20 53 51  tex. {F17020} SQ
2b3e0 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20  Lite is careful 
2b3f0 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76  to deallocate ev
2b400 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  ery.** dynamic m
2b410 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c  utex that it all
2b420 6f 63 61 74 65 73 2e 20 7b 55 31 37 30 32 31 7d  ocates. {U17021}
2b430 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   The dynamic mut
2b440 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65  exes must not be
2b450 20 69 6e 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e   in .** use when
2b460 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
2b470 63 61 74 65 64 2e 20 7b 55 31 37 30 32 32 7d 20  cated. {U17022} 
2b480 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65  Attempting to de
2b490 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69  allocate a stati
2b4a0 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c  c.** mutex resul
2b4b0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
2b4c0 62 65 68 61 76 69 6f 72 2e 20 7b 46 31 37 30 32  behavior. {F1702
2b4d0 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20  3} SQLite never 
2b4e0 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61  deallocates.** a
2b4f0 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b   static mutex. {
2b500 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  END}.**.** The s
2b510 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
2b520 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  er() and sqlite3
2b530 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75  _mutex_try() rou
2b540 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a  tines attempt.**
2b550 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65   to enter a mute
2b560 78 2e 20 7b 46 31 37 30 32 34 7d 20 49 66 20 61  x. {F17024} If a
2b570 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73  nother thread is
2b580 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20   already within 
2b590 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71  the mutex,.** sq
2b5a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
2b5b0 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61  r() will block a
2b5c0 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
2b5d0 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75  _try() will retu
2b5e0 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  rn.** SQLITE_BUS
2b5f0 59 2e 20 7b 46 31 37 30 32 35 7d 20 20 54 68 65  Y. {F17025}  The
2b600 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
2b610 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ry() interface r
2b620 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
2b630 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73  .** upon success
2b640 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 46 31 37  ful entry.  {F17
2b650 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65  026} Mutexes cre
2b660 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ated using.** SQ
2b670 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
2b680 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65  SIVE can be ente
2b690 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
2b6a0 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  es by the same t
2b6b0 68 72 65 61 64 2e 0a 2a 2a 20 7b 46 31 37 30 32  hread..** {F1702
2b6c0 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73 65 73  7} In such cases
2b6d0 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d   the,.** mutex m
2b6e0 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e  ust be exited an
2b6f0 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66   equal number of
2b700 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e   times before an
2b710 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
2b720 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 55 31 37  can enter.  {U17
2b730 30 32 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65  028} If the same
2b740 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
2b750 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
2b760 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65  .** kind of mute
2b770 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  x more than once
2b780 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
2b790 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2b7a0 7b 46 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20  {F17029} SQLite 
2b7b0 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62  will never exhib
2b7c0 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76  it.** such behav
2b7d0 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75  ior in its own u
2b7e0 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 20 7b  se of mutexes. {
2b7f0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  END}.**.** Some 
2b800 73 79 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e  systems (ex: win
2b810 64 6f 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74  dows95) do not t
2b820 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70  he operation imp
2b830 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73  lemented by.** s
2b840 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
2b850 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79  ().  On those sy
2b860 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d  stems, sqlite3_m
2b870 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a  utex_try() will.
2b880 2a 2a 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ** always return
2b890 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b   SQLITE_BUSY.  {
2b8a0 46 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69  F17030} The SQLi
2b8b0 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65  te core only eve
2b8c0 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65  r uses.** sqlite
2b8d0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73  3_mutex_try() as
2b8e0 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e   an optimization
2b8f0 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65   so this is acce
2b900 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ptable behavior.
2b910 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
2b920 37 30 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65  7031} The sqlite
2b930 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20  3_mutex_leave() 
2b940 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20  routine exits a 
2b950 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a  mutex that was.*
2b960 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74  * previously ent
2b970 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65  ered by the same
2b980 20 74 68 72 65 61 64 2e 20 20 7b 55 31 37 30 33   thread.  {U1703
2b990 32 7d 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a  2} The behavior.
2b9a0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ** is undefined 
2b9b0 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20  if the mutex is 
2b9c0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  not currently en
2b9d0 74 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  tered by the.** 
2b9e0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f  calling thread o
2b9f0 72 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  r is not current
2ba00 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b  ly allocated.  {
2ba10 46 31 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77  F17033} SQLite w
2ba20 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20  ill.** never do 
2ba30 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a  either. {END}.**
2ba40 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ba50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
2ba60 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
2ba70 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
2ba80 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  )]..*/.sqlite3_m
2ba90 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
2baa0 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
2bab0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
2bac0 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
2bad0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
2bae0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
2baf0 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
2bb00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
2bb10 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
2bb20 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
2bb30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
2bb40 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
2bb50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2bb60 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66  REF: Mutex Verif
2bb70 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20  cation Routines 
2bb80 7b 46 31 37 30 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17080}.**.** T
2bb90 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
2bba0 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69  _held() and sqli
2bbb0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
2bbc0 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  d() routines.** 
2bbd0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
2bbe0 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65   use inside asse
2bbf0 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e  rt() statements.
2bc00 20 7b 46 31 37 30 38 31 7d 20 54 68 65 20 53 51   {F17081} The SQ
2bc10 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
2bc20 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
2bc30 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
2bc40 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
2bc50 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
2bc60 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
2bc70 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
2bc80 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
2bc90 20 20 7b 46 31 37 30 38 32 7d 20 54 68 65 20 63    {F17082} The c
2bca0 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76  ore only.** prov
2bcb0 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ides implementat
2bcc0 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72  ions for these r
2bcd0 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20  outines when it 
2bce0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
2bcf0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ith the SQLITE_D
2bd00 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 55 31 37  EBUG flag.  {U17
2bd10 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75  087} External mu
2bd20 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
2bd30 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20  ons.** are only 
2bd40 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
2bd50 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ide these routin
2bd60 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42  es if SQLITE_DEB
2bd70 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64  UG is.** defined
2bd80 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69   and if NDEBUG i
2bd90 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a  s not defined..*
2bda0 2a 0a 2a 2a 20 7b 46 31 37 30 38 33 7d 20 54 68  *.** {F17083} Th
2bdb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
2bdc0 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20  uld return true 
2bdd0 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20  if the mutex in 
2bde0 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a  their argument.*
2bdf0 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74  * is held or not
2be00 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76   held, respectiv
2be10 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c  ely, by the call
2be20 69 6e 67 20 74 68 72 65 61 64 2e 20 7b 45 4e 44  ing thread. {END
2be30 7d 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d  }.**.** {X17084}
2be40 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2be50 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
2be60 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
2be70 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
2be80 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
2be90 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
2bea0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6d 70 6c  ..** If the impl
2beb0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
2bec0 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b  not provide work
2bed0 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ing.** versions 
2bee0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2bef0 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20  s, it should at 
2bf00 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74  least provide st
2bf10 75 62 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61  ubs.** that alwa
2bf20 79 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  ys return true s
2bf30 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20  o that one does 
2bf40 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73  not get spurious
2bf50 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e 20 66 61  .** assertion fa
2bf60 69 6c 75 72 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a  ilures. {END}.**
2bf70 0a 2a 2a 20 7b 46 31 37 30 38 35 7d 20 49 66 20  .** {F17085} If 
2bf80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
2bf90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
2bfa0 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ld() is a NULL p
2bfb0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74  ointer then.** t
2bfc0 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  he routine shoul
2bfd0 64 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e  d return 1.  {EN
2bfe0 44 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f  D} This seems co
2bff0 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20  unter-intuitive 
2c000 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79  since.** clearly
2c010 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f   the mutex canno
2c020 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20  t be held if it 
2c030 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20  does not exist. 
2c040 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20   But the.** the 
2c050 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78  reason the mutex
2c060 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
2c070 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62  is because the b
2c080 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75  uild is not.** u
2c090 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41  sing mutexes.  A
2c0a0 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e  nd we do not wan
2c0b0 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63  t the assert() c
2c0c0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
2c0d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2c0e0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f  _mutex_held() to
2c0f0 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d   fail, so a non-
2c100 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a  zero return is.*
2c110 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  * the appropriat
2c120 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20  e thing to do.  
2c130 7b 46 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c  {F17086} The sql
2c140 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
2c150 6c 64 28 29 20 0a 2a 2a 20 69 6e 74 65 72 66 61  ld() .** interfa
2c160 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72  ce should also r
2c170 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76  eturn 1 when giv
2c180 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2c190 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
2c1a0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c  3_mutex_held(sql
2c1b0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
2c1c0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
2c1d0 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  notheld(sqlite3_
2c1e0 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
2c1f0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
2c200 54 79 70 65 73 20 7b 46 31 37 30 30 31 7d 0a 2a  Types {F17001}.*
2c210 2a 0a 2a 2a 20 7b 46 31 37 30 30 32 7d 20 54 68  *.** {F17002} Th
2c220 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
2c230 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66  _alloc()] interf
2c240 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ace takes a sing
2c250 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  le argument.** w
2c260 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74  hich is one of t
2c270 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
2c280 73 74 61 6e 74 73 2e 20 7b 45 4e 44 7d 0a 2a 2f  stants. {END}.*/
2c290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c2a0 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20  MUTEX_FAST      
2c2b0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
2c2c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
2c2d0 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31  CURSIVE        1
2c2e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c2f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
2c300 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65  TER    2.#define
2c310 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
2c320 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33  ATIC_MEM       3
2c330 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c    /* sqlite3_mal
2c340 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  loc() */.#define
2c350 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
2c360 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34  ATIC_MEM2      4
2c370 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c    /* sqlite3_rel
2c380 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f  ease_memory() */
2c390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c3a0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
2c3b0 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  G      5  /* sql
2c3c0 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f  ite3_random() */
2c3d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c3e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
2c3f0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75         6  /* lru
2c400 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f   page list */../
2c410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
2c420 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c  ow-Level Control
2c430 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c   Of Database Fil
2c440 65 73 20 7b 46 31 31 33 30 30 7d 0a 2a 2a 0a 2a  es {F11300}.**.*
2c450 2a 20 7b 46 31 31 33 30 31 7d 20 54 68 65 20 5b  * {F11301} The [
2c460 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
2c470 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
2c480 65 20 6d 61 6b 65 73 20 61 20 64 69 72 65 63 74  e makes a direct
2c490 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20   call to the.** 
2c4a0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
2c4b0 68 6f 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  hod for the [sql
2c4c0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
2c4d0 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
2c4e0 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 72  ed.** with a par
2c4f0 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
2c500 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2c510 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2c520 6e 74 2e 20 7b 46 31 31 33 30 32 7d 20 54 68 65  nt. {F11302} The
2c530 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
2c540 64 61 74 61 62 61 73 65 20 69 73 20 74 68 65 20  database is the 
2c550 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2c560 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 79   the database by
2c570 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
2c580 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d  "lang_attach.htm
2c590 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51  l">ATTACH</a> SQ
2c5a0 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f  L command that o
2c5b0 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74  pened the.** dat
2c5c0 61 62 61 73 65 2e 20 7b 46 31 31 33 30 33 7d 20  abase. {F11303} 
2c5d0 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d  To control the m
2c5e0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
2c5f0 65 2c 20 75 73 65 20 74 68 65 20 6e 61 6d 65 20  e, use the name 
2c600 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e  "main".** or a N
2c610 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 7b 46 31  ULL pointer. {F1
2c620 31 33 30 34 7d 20 54 68 65 20 74 68 69 72 64 20  1304} The third 
2c630 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
2c640 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f  eters to this ro
2c650 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73  utine.** are pas
2c660 73 65 64 20 64 69 72 65 63 74 6c 79 20 74 68 72  sed directly thr
2c670 6f 75 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f  ough to the seco
2c680 6e 64 20 61 6e 64 20 74 68 69 72 64 20 70 61 72  nd and third par
2c690 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68  ameters of.** th
2c6a0 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
2c6b0 65 74 68 6f 64 2e 20 20 7b 46 31 31 33 30 35 7d  ethod.  {F11305}
2c6c0 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
2c6d0 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65 43 6f  e of the xFileCo
2c6e0 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20  ntrol.** method 
2c6f0 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65 74 75  becomes the retu
2c700 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
2c710 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20   routine..**.** 
2c720 7b 46 31 31 33 30 36 7d 20 49 66 20 74 68 65 20  {F11306} If the 
2c730 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2c740 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 20   (zDbName) does 
2c750 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 20 6e 61  not match the na
2c760 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65  me of any.** ope
2c770 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  n database file,
2c780 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 52   then SQLITE_ERR
2c790 4f 52 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OR is returned. 
2c7a0 7b 46 31 31 33 30 37 7d 20 54 68 69 73 20 65 72  {F11307} This er
2c7b0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e  ror.** code is n
2c7c0 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e  ot remembered an
2c7d0 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65  d will not be re
2c7e0 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74  called by [sqlit
2c7f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a  e3_errcode()].**
2c800 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
2c810 6d 73 67 28 29 5d 2e 20 7b 55 31 31 33 30 38 7d  msg()]. {U11308}
2c820 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
2c830 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
2c840 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73  hod might.** als
2c850 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  o return SQLITE_
2c860 45 52 52 4f 52 2e 20 20 7b 55 31 31 33 30 39 7d  ERROR.  {U11309}
2c870 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79   There is no way
2c880 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20   to distinguish 
2c890 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e  between.** an in
2c8a0 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20  correct zDbName 
2c8b0 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52  and an SQLITE_ER
2c8c0 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20  ROR return from 
2c8d0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a  the underlying.*
2c8e0 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  * xFileControl m
2c8f0 65 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ethod. {END}.**.
2c900 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51  ** See also: [SQ
2c910 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
2c920 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  TATE].*/.int sql
2c930 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
2c940 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  l(sqlite3*, cons
2c950 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
2c960 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b   int op, void*);
2c970 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65  ../*.** Undo the
2c980 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 65   hack that conve
2c990 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rts floating poi
2c9a0 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 65  nt types to inte
2c9b0 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64  ger for.** build
2c9c0 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 20  s on processors 
2c9d0 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67  without floating
2c9e0 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a   point support..
2c9f0 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2ca00 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2ca10 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f 75  OINT.# undef dou
2ca20 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  ble.#endif..#ifd
2ca30 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d  ef __cplusplus.}
2ca40 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 20    /* End of the 
2ca50 27 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 6f  'extern "C"' blo
2ca60 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e  ck */.#endif.#en
2ca70 64 69 66 0a                                      dif.