/ Hex Artifact Content
Login

Artifact be6caded9ecc1d0da60670334edfb3426cc256d2:


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 38 33 20 32 30 30 38 2f  in,v 1.283 2008/
05f0: 30 31 2f 33 31 20 31 37 3a 32 31 3a 32 32 20 64  01/31 17:21:22 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f  extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74  *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65  hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a  header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0840: 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 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 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
0ba0: 2a 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20  ** {F10011} The 
0bb0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23  SQLITE_VERSION #
0bc0: 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71  define in the sq
0bd0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66  lite3.h header f
0be0: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
0bf0: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0c00: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0c10: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0c20: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0c30: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0c40: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0c50: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0c60: 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68  *.** {F10014} Th
0c70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c80: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0c90: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
0ca0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0cb0: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0cc0: 65 20 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20  e  (X*1000000 + 
0cd0: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72  Y*1000 + Z) wher
0ce0: 65 20 58 2c 20 59 2c 20 61 6e 64 0a 2a 2a 20 20  e X, Y, and.**  
0cf0: 20 20 20 20 20 20 20 20 5a 20 61 72 65 20 74 68          Z are th
0d00: 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c  e major version,
0d10: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20   minor version, 
0d20: 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  and release numb
0d30: 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  er..*/.#define S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
0d50: 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22        "--VERS--"
0d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0d70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d  VERSION_NUMBER -
0d80: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
0d90: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
0da0: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
0db0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
0dc0: 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a 20  ers {F10020}.** 
0dd0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
0de0: 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  3_version.**.** 
0df0: 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70  These features p
0e00: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
0e10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
0e20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0e30: 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49  ON].** and [SQLI
0e40: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0e50: 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74  R] #defines in t
0e60: 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61  he header, but a
0e70: 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  re associated.**
0e80: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
0e90: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
0ea0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43   header file.  C
0eb0: 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d  autious programm
0ec0: 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63  ers might.** inc
0ed0: 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20  lude a check in 
0ee0: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
0ef0: 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  n to verify that
0f00: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62   .** sqlite3_lib
0f10: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
0f20: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
0f30: 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 5b 53  the value .** [S
0f40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0f50: 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  MBER]..**.** The
0f60: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
0f70: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
0f80: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20  eturns the same 
0f90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
0fa0: 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69  s.** in the sqli
0fb0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
0fc0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
0fd0: 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  The function is 
0fe0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
0ff0: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
1000: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
1010: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  lly do not have 
1020: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1030: 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74   string.** const
1040: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
1050: 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  DLL..**.** INVAR
1060: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1070: 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0021} The [sqlit
1080: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1090: 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  mber()] interfac
10a0: 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  e returns an int
10b0: 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
10c0: 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54   equal to [SQLIT
10d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
10e0: 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32  ]. .**.** {F1002
10f0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1100: 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20  version] string 
1110: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1120: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 68  s the text of th
1130: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
1140: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1150: 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46  tring. .**.** {F
1160: 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  10023} The [sqli
1170: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1180: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1190: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
11a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
11b0: 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e  [sqlite3_version
11c0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
11d0: 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  t..*/.SQLITE_EXT
11e0: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
11f0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1200: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1210: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1220: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
1230: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1240: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
1250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
1260: 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65  st To See If The
1270: 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65   Library Is Thre
1280: 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d 0a  adsafe {F10100}.
1290: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
12a0: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
12b0: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
12c0: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
12d0: 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  he SQLITE_THREAD
12e0: 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 65 73  SAFE C preproces
12f0: 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72 75  sor macro is tru
1300: 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  e, mutexes.** ar
1310: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1320: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1330: 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20 6d  fe.  When that m
1340: 61 63 72 6f 20 6f 73 20 66 61 6c 73 65 2c 0a 2a  acro os false,.*
1350: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1360: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1370: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1380: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1390: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
13a0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
13b0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
13c0: 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d 65 61  * There is a mea
13d0: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
13e0: 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f 72 20  nce penalty for 
13f0: 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  enabling mutexes
1400: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1410: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1420: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1430: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1440: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1450: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1460: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1470: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1480: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
1490: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14e0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
14f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1500: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1510: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1520: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1530: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1540: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1550: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1560: 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  e SQLITE_THREADS
1570: 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  AFE macro..**.**
1580: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1590: 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65 20  ** {F10101} The 
15a0: 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
15b0: 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  afe()] function 
15c0: 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 6f 20  returns nonzero 
15d0: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
15e0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
15f0: 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 74 65  ed with its mute
1600: 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 7a  xes enabled or z
1610: 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ero.**          
1620: 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  if SQLite was co
1630: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1640: 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f  xes disabled..*/
1650: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
1660: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
1670: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1680: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1690: 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32 30  ion Handle {F120
16a0: 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
16b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
16c0: 63 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  ction}.**.** Eac
16d0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
16e0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
16f0: 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72  ented by pointer
1700: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
1710: 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65  of the.** opaque
1720: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
1730: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
1740: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
1750: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
1760: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
1770: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
1780: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1790: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
17a0: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
17b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
17c0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
17d0: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 0a  ts constructors.
17e0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
17f0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73 20  close()] is its 
1800: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
1810: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
1820: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1830: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65  (such as [sqlite
1840: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1850: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1860: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
1870: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
1880: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
1890: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
18a0: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
18b0: 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  s on this.** obj
18c0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
18d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
18e0: 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  qlite3;.../*.** 
18f0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
1900: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b   Integer Types {
1910: 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F10200}.** KEYWO
1920: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
1930: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
1940: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1950: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
1960: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
1970: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
1980: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
1990: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
19a0: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
19b0: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
19c0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
19d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
19e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
19f0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
1a00: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
1a10: 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 69 6f  ype.** definitio
1a20: 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65 5f  ns.  The sqlite_
1a30: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
1a40: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
1a50: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 20 66  e.** supported f
1a60: 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1a70: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
1a80: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1a90: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30 31  S:.**.** {F10201
1aa0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e  } The [sqlite_in
1ab0: 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  t64] and [sqlite
1ac0: 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73  3_int64] types s
1ad0: 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 20 20  pecify a.**     
1ae0: 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 67 6e       64-bit sign
1af0: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1b00: 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20 5b  * {F10202} The [
1b10: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61  sqlite_uint64] a
1b20: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74  nd [sqlite3_uint
1b30: 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69 66  64] types specif
1b40: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1b50: 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1b60: 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64  integer..*/.#ifd
1b70: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1b80: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
1b90: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1ba0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1bb0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1bc0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
1bd0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
1be0: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
1bf0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
1c00: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
1c10: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
1c20: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
1c30: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1c40: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
1c50: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1c60: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
1c70: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1c80: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1c90: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
1ca0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
1cb0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
1cc0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
1cd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
1ce0: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
1cf0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
1d00: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
1d10: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
1d20: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
1d30: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
1d40: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
1d50: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
1d60: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
1d70: 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69  ting-point.*/.#i
1d80: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
1d90: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
1da0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
1db0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
1dc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1dd0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
1de0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1df0: 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a 0a  ion {F12010}.**.
1e00: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1e10: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
1e20: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
1e30: 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a 2a 2a  e3] object.  .**
1e40: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1e50: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
1e60: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
1e70: 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b 70 72  lize] all.** [pr
1e80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e90: 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  s] and.** [sqlit
1ea0: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
1eb0: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 6c 69  close] all [sqli
1ec0: 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42 73  te3_blob | BLOBs
1ed0: 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ] .** associated
1ee0: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
1ef0: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
1f00: 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  .** to attemptin
1f10: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 5b  g to close the [
1f20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
1f30: 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 68 61  .**.** <todo>Wha
1f40: 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 65 6e  t happens to pen
1f50: 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e  ding transaction
1f60: 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a 2a 20  s?  Are they.** 
1f70: 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f 72 20  rolled back, or 
1f80: 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f 64 6f  abandoned?</todo
1f90: 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
1fa0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  TS:.**.** {F1201
1fb0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1fc0: 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66 61  close()] interfa
1fd0: 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20 5b  ce destroys an [
1fe0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a  sqlite3] object.
1ff0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
2000: 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f 72  cated by a prior
2010: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2020: 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20 20  3_open()],.**   
2030: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2040: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
2050: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2060: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 32  ]..**.** {F12012
2070: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2080: 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  lose()] function
2090: 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d 65   releases all me
20a0: 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68 65  mory used by the
20b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
20c0: 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f 73  nection and clos
20d0: 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c 65  es all open file
20e0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 33  s..**.** {F12013
20f0: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
2100: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e  e connection con
2110: 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
2120: 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2130: 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61 76  ements] that hav
2140: 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20 20  e not been.**   
2150: 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65 64         finalized
2160: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2170: 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20 5b  alize()], then [
2180: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2190: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
21a0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
21b0: 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74 68  Y] and leaves th
21c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
21d0: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 34  n..**.** {F12014
21e0: 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65 33  } Giving sqlite3
21f0: 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c 20  _close() a NULL 
2200: 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2210: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2220: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
2230: 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20 54  **.** {U12015} T
2240: 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
2250: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2260: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73 71  ] must be an [sq
2270: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a 2a  lite3] object.**
2280: 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
2290: 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  r previously obt
22a0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
22b0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 74  te3_open()] or t
22c0: 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
22d0: 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 4e  equivalent, or N
22e0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30  ULL..**.** {U120
22f0: 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74 65  16} The paramete
2300: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2310: 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74 20  ose()] must not 
2320: 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69 6f  have been previo
2330: 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
2340: 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20   closed..*/.int 
2350: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
2360: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
2370: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
2380: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2390: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
23a0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
23b0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
23c0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
23d0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
23e0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
23f0: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2400: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2410: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2420: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2430: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
2440: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
2450: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
2460: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 46  ion Interface {F
2470: 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12100}.**.** The
2480: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2490: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
24a0: 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66  onvenient way of
24b0: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65 20   running.** one 
24c0: 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61 74  or more SQL stat
24d0: 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 61  ements without a
24e0: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
24f0: 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   The.** SQL stat
2500: 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65  ements are passe
2510: 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f  d in as the seco
2520: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
2530: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
2540: 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65 6e  ).  The statemen
2550: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2560: 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20 75   one by one.** u
2570: 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 65  ntil either an e
2580: 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72  rror or an inter
2590: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
25a0: 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c 20  red or.** until 
25b0: 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e  they are all don
25c0: 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72 61  e.  The 3rd para
25d0: 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74 69  meter is an opti
25e0: 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  onal.** callback
25f0: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
2600: 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72   once for each r
2610: 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79 20  ow of any query 
2620: 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64 75  results.** produ
2630: 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20 73  ced by the SQL s
2640: 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20  tatements.  The 
2650: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 65  5th parameter te
2660: 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20  lls where.** to 
2670: 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20  write any error 
2680: 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  messages..**.** 
2690: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
26a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
26b0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74  implemented in t
26c0: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  erms of.** [sqli
26d0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26e0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
26f0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2700: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
2710: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2720: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  ec() routine doe
2730: 73 20 6e 6f 74 68 69 6e 67 20 74 68 61 74 20 63  s nothing that c
2740: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a  annot be done.**
2750: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
2760: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2770: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2780: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2790: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
27a0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
27b0: 20 6a 75 73 74 20 61 20 63 6f 6e 76 65 6e 69 65   just a convenie
27c0: 6e 74 20 77 72 61 70 70 65 72 2e 0a 2a 2a 0a 2a  nt wrapper..**.*
27d0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
27e0: 20 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 54 68   .** {F12101} Th
27f0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
2800: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 65 76 61  )] interface eva
2810: 6c 75 61 74 65 73 20 7a 65 72 6f 20 6f 72 20 6d  luates zero or m
2820: 6f 72 65 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20  ore UTF-8.**    
2830: 20 20 20 20 20 20 65 6e 63 6f 64 65 64 2c 20 73        encoded, s
2840: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
2850: 65 64 2c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ed, SQL statemen
2860: 74 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ts in the.**    
2870: 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
2880: 6e 61 74 65 64 20 73 74 72 69 6e 67 20 6f 66 20  nated string of 
2890: 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
28a0: 72 20 77 69 74 68 69 6e 20 74 68 65 0a 2a 2a 20  r within the.** 
28b0: 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
28c0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
28d0: 5d 20 6f 62 6a 65 63 74 20 67 69 76 65 6e 20 69  ] object given i
28e0: 6e 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  n the 1st parame
28f0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ter..**.** {F121
2900: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  04} The return v
2910: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
2920: 5f 65 78 65 63 28 29 5d 20 69 73 20 53 51 4c 49  _exec()] is SQLI
2930: 54 45 5f 4f 4b 20 69 66 20 61 6c 6c 0a 2a 2a 20  TE_OK if all.** 
2940: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
2950: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63  tements run succ
2960: 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  essfully..**.** 
2970: 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 65 74  {F12105} The ret
2980: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  urn value of [sq
2990: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
29a0: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
29b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
29c0: 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 6f 64 65  -zero error code
29d0: 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74   if any SQL stat
29e0: 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a  ement fails..**.
29f0: 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20 6f  ** {F12107} If o
2a00: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2a10: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2a20: 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69   handed to [sqli
2a30: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
2a40: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72          return r
2a50: 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33  esults and the 3
2a60: 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
2a70: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a  not NULL, then.*
2a80: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
2a90: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2aa0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2ab0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2ac0: 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  is.**          i
2ad0: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
2ae0: 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75  each row of resu
2af0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
2b00: 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  0} If the callba
2b10: 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ck returns a non
2b20: 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e  -zero value then
2b30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2b40: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
2b50: 6c 6c 20 61 62 6f 72 74 65 64 20 74 68 65 20 53  ll aborted the S
2b60: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20  QL statement it 
2b70: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61  is currently eva
2b80: 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20  luating,.**     
2b90: 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75       skip all su
2ba0: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
2bb0: 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74  tements, and ret
2bc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52  urn [SQLITE_ABOR
2bd0: 54 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T]..**          
2be0: 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65  <todo>What happe
2bf0: 6e 73 20 74 6f 20 2a 65 72 72 6d 73 67 20 68 65  ns to *errmsg he
2c00: 72 65 3f 20 20 44 6f 65 73 20 74 68 65 20 72 65  re?  Does the re
2c10: 73 75 6c 74 20 63 6f 64 65 20 66 6f 72 0a 2a 2a  sult code for.**
2c20: 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
2c30: 33 5f 65 72 72 63 6f 64 65 28 29 20 67 65 74 20  3_errcode() get 
2c40: 73 65 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  set?</todo>.**.*
2c50: 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b  * {F12113} The [
2c60: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2c70: 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 70 61 73  routine will pas
2c80: 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65  s its 4th parame
2c90: 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20  ter through.**  
2ca0: 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31          as the 1
2cb0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  st parameter of 
2cc0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2cd0: 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65  .** {F12116} The
2ce0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2cf0: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
2d00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2d10: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
2d20: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
2d30: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
2d40: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2d50: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a  current row of.*
2d60: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
2d70: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39  t..**.** {F12119
2d80: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
2d90: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
2da0: 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72 61  ets the 3rd para
2db0: 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a 2a  meter of its .**
2dc0: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
2dd0: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
2de0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
2df0: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
2e00: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e10: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
2e20: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2e30: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
2e40: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
2e50: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
2e60: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2e70: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
2e80: 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b  * {F12122} The [
2e90: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2ea0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65  routine sets the
2eb0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   4th parameter o
2ec0: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  f its.**        
2ed0: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
2ee0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2ef0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
2f00: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
2f10: 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f           names o
2f20: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
2f30: 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   as obtained fro
2f40: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
2f50: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
2f60: 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68 65   {F12125} If the
2f70: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2f80: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
2f90: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
2fa0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2fb0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65 76  ite3_exec()] nev
2fc0: 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c  er invokes a cal
2fd0: 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72  lback.  All quer
2fe0: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
2ff0: 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e 74  sults are silent
3000: 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  ly discarded..**
3010: 0a 2a 2a 20 7b 46 31 32 31 32 38 7d 20 49 66 20  .** {F12128} If 
3020: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3030: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3040: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3050: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3060: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3070: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  s handed to [sql
3080: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 74 68 65  ite3_exec()] the
3090: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
30a0: 29 5d 20 77 69 6c 6c 0a 2a 2a 20 20 20 20 20 20  )] will.**      
30b0: 20 20 20 20 72 65 74 75 72 6e 20 61 6e 20 5b 65      return an [e
30c0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
30d0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
30e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 31  ]..**.** {F12131
30f0: 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  } If an error oc
3100: 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 69  curs while parsi
3110: 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ng or evaluating
3120: 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c 0a   any of the SQL.
3130: 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
3140: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ed to [sqlite3_e
3150: 78 65 63 28 29 5d 20 61 6e 64 20 69 66 20 74 68  xec()] and if th
3160: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3170: 28 65 72 72 6d 73 67 29 0a 2a 2a 20 20 20 20 20  (errmsg).**     
3180: 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33       to [sqlite3
3190: 5f 65 78 65 63 28 29 5d 20 69 73 20 6e 6f 74 20  _exec()] is not 
31a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6e 20 65 72  NULL, then an er
31b0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 0a 2a  ror message is.*
31c0: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
31d0: 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 65  ated using the e
31e0: 71 75 69 76 61 6c 65 6e 74 20 6f 66 20 5b 73 71  quivalent of [sq
31f0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
3200: 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
3210: 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64 65   *errmsg is made
3220: 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 61   to point to tha
3230: 74 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  t message..**.**
3240: 20 7b 46 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {F12134} The [s
3250: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3260: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
3270: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
3280: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
3290: 2a 65 72 72 6d 73 67 20 69 66 20 65 72 72 6d 73  *errmsg if errms
32a0: 67 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  g is NULL or if 
32b0: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72  there are no err
32c0: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ors..**.** {F121
32d0: 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  37} The [sqlite3
32e0: 5f 65 78 65 63 28 29 5d 20 66 75 6e 63 74 69 6f  _exec()] functio
32f0: 6e 20 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  n sets the error
3300: 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
3310: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63  e.**          ac
3320: 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
3330: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3340: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3350: 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c  rmsg()]..**.** L
3360: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
3370: 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66  * {U12141} The f
3380: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
3390: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
33a0: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61  )] must be an va
33b0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20  lid and open.** 
33c0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
33d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
33e0: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54  **.** {U12142} T
33f0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
3400: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
3410: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a  be closed while.
3420: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3430: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3440: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20  running..** .** 
3450: 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {U12143} The cal
3460: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ling function is
3470: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
3480: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
3490: 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  free.**         
34a0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
34b0: 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74   *errmsg is left
34c0: 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63   pointing at onc
34d0: 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20  e the error.**  
34e0: 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65 20          message 
34f0: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
3500: 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31  ded..**.** {U121
3510: 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74  45} The SQL stat
3520: 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68  ement text in th
3530: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3540: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3550: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
3560: 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68  must remain unch
3570: 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c  anged while [sql
3580: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3590: 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
35a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
35b0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
35c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
35e0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
35f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
3600: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
3610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3620: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
3630: 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  uted */.  int (*
3640: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3650: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3660: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3670: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3680: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
3690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
36b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
36c0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
36d0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
36e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3700: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3710: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3720: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3730: 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20  des {F10210}.** 
3740: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3750: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3760: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3770: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
3780: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
3790: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
37a0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
37b0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
37c0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
37d0: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
37e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
37f0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  .** See also: [S
3800: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
3810: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
3820: 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65  lt codes].*/.#de
3830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
3840: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
3850: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
3860: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
3870: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
3880: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3890: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
38a0: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
38b0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
38c0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
38d0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
38e0: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
38f0: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
3900: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
3910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
3920: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
3930: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
3940: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
3950: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
3960: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
3970: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
3980: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
3990: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
39a0: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
39b0: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
39c0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
39d0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
39e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
39f0: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
3a00: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
3a10: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
3a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
3a30: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
3a40: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
3a50: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
3a60: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
3a70: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
3a80: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
3a90: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
3aa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3ab0: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
3ac0: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
3ad0: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
3ae0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
3af0: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
3b00: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
3b10: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
3b20: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
3b30: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
3b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
3b50: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
3b60: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
3b70: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
3b80: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
3b90: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
3ba0: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54  D    12   /* NOT
3bb0: 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20   USED. Table or 
3bc0: 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64  record not found
3bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3be0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
3bf0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
3c00: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
3c10: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
3c20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3c30: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
3c40: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
3c50: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
3c60: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
3c70: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
3c80: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f  OL    15   /* NO
3c90: 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65  T USED. Database
3ca0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
3cb0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
3cc0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
3cd0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
3ce0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
3cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
3d00: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
3d10: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
3d20: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
3d30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3d40: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
3d50: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
3d60: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
3d70: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
3d80: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
3d90: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
3da0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
3db0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
3dc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3dd0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
3de0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
3df0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
3e00: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
3e10: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
3e20: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
3e30: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
3e40: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
3e50: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
3e60: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
3e70: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
3e80: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
3e90: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
3ea0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
3eb0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
3ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ed0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
3ee0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
3ef0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
3f00: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
3f10: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
3f20: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
3f30: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3f40: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
3f50: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
3f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
3f70: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
3f80: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
3f90: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
3fa0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
3fb0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
3fc0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
3fd0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
3fe0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
3ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4000: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4010: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4020: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4030: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4040: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4050: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4060: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4070: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46   Result Codes {F
4080: 31 30 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10220}.** KEYWOR
4090: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
40a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
40b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
40c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
40d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
40e0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
40f0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4100: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4110: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4120: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
4130: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
4140: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
4150: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4160: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4170: 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e  hown that.** man
4180: 79 20 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c  y of these resul
4190: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
41a0: 63 6f 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  course-grained. 
41b0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
41c0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
41d0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
41e0: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
41f0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4200: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4210: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4220: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4230: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4240: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4250: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4260: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4270: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4280: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
4290: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
42a0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
42b0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
42c0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
42d0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
42e0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
42f0: 6c 65 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20  led.** for each 
4300: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4310: 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73  ion using the [s
4320: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4330: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a  result_codes()].
4340: 2a 2a 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53  ** API..** .** S
4350: 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c  ome of the avail
4360: 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65  able extended re
4370: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c  sult codes are l
4380: 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f  isted here..** O
4390: 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68  ne may expect th
43a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65  e number of exte
43b0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
43c0: 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64  s will be expand
43d0: 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20  .** over time.  
43e0: 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73  Software that us
43f0: 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  es extended resu
4400: 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20  lt codes should 
4410: 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65  expect.** to see
4420: 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65   new result code
4430: 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
4440: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
4450: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
4460: 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20  _OK result code 
4470: 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78  will never be ex
4480: 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c  tended.  It will
4490: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78   always.** be ex
44a0: 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a  actly zero..** .
44b0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
44c0: 2a 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68  *.** {F10223} Th
44d0: 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
44e0: 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20  for an extended 
44f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61  result code alwa
4500: 79 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ys contains.**  
4510: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
4520: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
4530: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
4540: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34  x..**.** {F10224
4550: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
4560: 20 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74   code names cont
4570: 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22  ain a single "_"
4580: 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a   character..**.*
4590: 2a 20 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e  * {F10225} Exten
45a0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
45b0: 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77  names contain tw
45c0: 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68  o or more "_" ch
45d0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
45e0: 7b 46 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d  {F10226} The num
45f0: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e  eric value of an
4600: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4610: 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74   code contains t
4620: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
4630: 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20  umeric value of 
4640: 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  its correspondin
4650: 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  g primary result
4660: 20 63 6f 64 65 20 69 74 0a 2a 2a 20 20 20 20 20   code it.**     
4670: 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20 73       its least s
4680: 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74  ignificant 8 bit
4690: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
46a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
46b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
46c0: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
46f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4700: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
4710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4720: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 28  _WRITE         (
4730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4740: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
4750: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
4760: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4770: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4790: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
47a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
47b0: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
47c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
47d0: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
47e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
47f0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
4800: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
4810: 41 54 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AT         (SQLI
4820: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
4830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4840: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
4850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4860: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4880: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4890: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
48a0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
48b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
48c0: 4c 45 54 45 20 20 20 20 20 20 20 20 28 53 51 4c  LETE        (SQL
48d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
48e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
48f0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
4900: 44 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  D       (SQLITE_
4910: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
4920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4930: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
4940: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4950: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 0a 2f 2a  R | (12<<8))../*
4960: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
4970: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
4980: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31  n Operations {F1
4990: 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0230}.**.** Thes
49a0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
49b0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
49c0: 65 20 69 6e 20 74 68 65 6e 0a 2a 2a 20 33 72 64  e in then.** 3rd
49d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
49e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
49f0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
4a00: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
4a10: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
4a20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
4a30: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
4a40: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
4a50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a60: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
4a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4a80: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
4a90: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
4aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4ab0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4ac0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
4ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4ae0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
4af0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
4b00: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
4b10: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
4b20: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
4b30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4b40: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
4b50: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
4b60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
4b70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4b80: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
4b90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
4ba0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4bb0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
4bc0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
4bd0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4be0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
4bf0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
4c00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4c10: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
4c20: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
4c30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4c40: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
4c50: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
4c60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4c70: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
4c80: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
4c90: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
4ca0: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
4cb0: 63 74 65 72 69 73 74 69 63 73 20 7b 46 31 30 32  cteristics {F102
4cc0: 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  40}.**.** The xD
4cd0: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
4ce0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
4cf0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4d00: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
4d10: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
4d20: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
4d30: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
4d40: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
4d50: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
4d60: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
4d70: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
4d80: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
4d90: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
4da0: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
4db0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
4dc0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
4dd0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
4de0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
4df0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
4e00: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
4e10: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
4e20: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
4e30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
4e40: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
4e50: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
4e60: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
4e70: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
4e80: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
4e90: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
4ea0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
4eb0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
4ec0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
4ed0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
4ee0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
4ef0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
4f00: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
4f10: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
4f20: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
4f30: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
4f40: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
4f50: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
4f60: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
4f70: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
4f80: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
4f90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
4fa0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
4fb0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
4fc0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
4fd0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
4fe0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
4ff0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
5000: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
5010: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5020: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
5030: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
5040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5050: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
5060: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5080: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
5090: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
50b0: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
50c0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
50d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
50e0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
50f0: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
5100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5110: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
5120: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5140: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
5150: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
5160: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5170: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
5180: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5190: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
51a0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
51b0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
51c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
51d0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
51e0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5200: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
5210: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
5220: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5230: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5240: 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F10250}.**.** 
5250: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
5260: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
5270: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
5280: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
5290: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
52a0: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
52b0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
52c0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
52d0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
52e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
52f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5300: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
5310: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
5320: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
5330: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
5340: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
5350: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
5360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5370: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
5380: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
5390: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
53a0: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
53b0: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
53c0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
53d0: 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a  s {F10260}.**.**
53e0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
53f0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
5400: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
5410: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5420: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
5430: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
5440: 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 74 68 65  on of the.** the
5450: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
5460: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
5470: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
5480: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
5490: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
54a0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
54b0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
54c0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
54d0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
54e0: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
54f0: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
5500: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5510: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
5520: 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  hed. The SQLITE_
5530: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65 61 6e  SYNC_NORMAL mean
5540: 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72  s .** to use nor
5550: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
5560: 6e 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54  ntics. The SQLIT
5570: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
5580: 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73   means .** to us
5590: 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  e Mac OS-X style
55a0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
55b0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f  d of fsync()..*/
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
55e0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
5600: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
5610: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
5620: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
5630: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
5640: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5650: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
5660: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b  en File Handle {
5670: 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e  F11110}.**.** An
5680: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
5690: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
56a0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
56b0: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
56c0: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
56d0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
56e0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
56f0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
5700: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
5710: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
5720: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
5730: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
5740: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
5750: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
5760: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
5770: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
5780: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5790: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
57a0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
57b0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
57c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
57d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
57e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
57f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
5800: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
5810: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
5820: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5830: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5840: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5850: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5860: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5870: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5880: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5890: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
58a0: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31  ods Object {F111
58b0: 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  20}.**.** Every 
58c0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
58d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
58e0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f   xOpen method co
58f0: 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72  ntains a pointer
5900: 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e   to.** an instan
5910: 63 65 20 6f 66 20 74 68 65 20 74 68 69 73 20 6f  ce of the this o
5920: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
5930: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a  ect defines the.
5940: 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  ** methods used 
5950: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5960: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67  us operations ag
5970: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
5980: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ile..**.** The f
5990: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
59a0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
59b0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
59c0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
59d0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
59e0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
59f0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
5a00: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20 20  mal fsync()..*  
5a10: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
5a20: 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20  e is an.** OS-X 
5a30: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
5a40: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
5a50: 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62  _DATA flag may b
5a60: 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a 20  e ORed in to.** 
5a70: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
5a80: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
5a90: 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20  he file and not 
5aa0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
5ab0: 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64 2e  to be.** synced.
5ac0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74 65  .** .** The inte
5ad0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
5ae0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5af0: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
5b00: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
5b10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5b30: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
5b40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b50: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
5b60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b70: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5b80: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
5b90: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5ba0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
5bb0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
5bc0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
5bd0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
5be0: 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54  the lock.  .** T
5bf0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
5c00: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c  dLock() method l
5c10: 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69  ooks.** to see i
5c20: 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  f any database c
5c30: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68 65  onnection, eithe
5c40: 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f  r in this.** pro
5c50: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
5c60: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
5c70: 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53  s holding an RES
5c80: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
5c90: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
5ca0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
5cb0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
5cc0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
5cd0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
5ce0: 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a  false if not..**
5cf0: 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f   .** The xFileCo
5d00: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
5d10: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
5d20: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
5d30: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
5d40: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
5d50: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
5d60: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
5d70: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
5d80: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
5d90: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
5da0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
5db0: 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  p" argument.** i
5dc0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70 63  s an integer opc
5dd0: 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 72 64  ode.   The third
5de0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
5df0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
5e00: 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 6e  r which is inten
5e10: 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69 6e  ded to be a poin
5e20: 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 75  ter.** to a stru
5e30: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
5e40: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
5e50: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
5e60: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
5e70: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
5e80: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
5e90: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
5ea0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
5eb0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
5ec0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
5ed0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
5ee0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
5ef0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
5f00: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
5f10: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
5f20: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
5f30: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
5f40: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
5f50: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
5f60: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
5f70: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
5f80: 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65  erves opcodes le
5f90: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
5fa0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a  its own use. .**
5fb0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
5fc0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
5fd0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
5fe0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
5ff0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6000: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6010: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6020: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6030: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6040: 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74 65  codes .** greate
6050: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
6060: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
6070: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
6080: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
6090: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
60a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
60b0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
60c0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
60d0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
60e0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
60f0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
6100: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
6110: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
6120: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6130: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6140: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6150: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6160: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6170: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
6180: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
6190: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
61a0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
61b0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
61c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
61d0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
61e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
61f0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
6200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6210: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
6220: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6230: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
6240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6250: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
6260: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6270: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
6280: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6290: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
62a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
62b0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
62c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
62d0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
62e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
62f0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
6300: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6310: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
6320: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6340: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6350: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6360: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6370: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
63a0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
63b0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
63c0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
63d0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
63e0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
63f0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6400: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6410: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6420: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6430: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6440: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6450: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6460: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6470: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6480: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6490: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
64a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
64b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
64c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
64d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
64e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
64f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6500: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6510: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6520: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6530: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6540: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6550: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6560: 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  e()..*/.typedef 
6570: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
6580: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
6590: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
65a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65b0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
65c0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
65d0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
65e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
65f0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
6600: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
6610: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6620: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6630: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
6640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
6650: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
6660: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
6670: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
6680: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
6690: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
66a0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
66b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
66c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
66d0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
66e0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
66f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
6710: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6720: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6730: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6740: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6750: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6760: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6770: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
6780: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
6790: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
67a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
67b0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
67c0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
67d0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
67e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
67f0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
6800: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
6810: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
6820: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
6830: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6840: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
6850: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
6860: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
6870: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
6880: 70 63 6f 64 65 73 20 7b 46 31 31 33 31 30 7d 0a  pcodes {F11310}.
6890: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
68a0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
68b0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
68c0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
68d0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
68e0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
68f0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
6900: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6910: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
6920: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
6930: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
6940: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
6950: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
6960: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
6970: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
6980: 61 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  ases the xFileCo
6990: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
69a0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
69b0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
69c0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
69d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
69e0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
69f0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
6a00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6a10: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
6a20: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
6a30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6a40: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
6a50: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
6a60: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
6a70: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
6a80: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
6a90: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
6aa0: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
6ab0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
6ac0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
6ad0: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
6ae0: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ned..*/.#define 
6af0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b00: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a  KSTATE        1.
6b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6b20: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 46   Mutex Handle {F
6b30: 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17110}.**.** The
6b40: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
6b50: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
6b60: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
6b70: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
6b80: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
6b90: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
6ba0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
6bb0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
6bc0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
6bd0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
6be0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6bf0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
6c00: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
6c10: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
6c20: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
6c30: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
6c40: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
6c50: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
6c60: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
6c70: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
6c80: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
6c90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
6ca0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6cb0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
6cc0: 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a 0a  ect {F11140}.**.
6cd0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
6ce0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
6cf0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
6d00: 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  ace between the.
6d10: 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  ** SQLite core a
6d20: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
6d30: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
6d40: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
6d50: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
6d60: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
6d70: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
6d80: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
6d90: 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e  .** The iVersion
6da0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
6db0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
6dc0: 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75   larger for futu
6dd0: 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
6de0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
6df0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
6e00: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
6e10: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
6e20: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
6e30: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
6e40: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
6e50: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
6e60: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6e70: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
6e80: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
6e90: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
6ea0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
6eb0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
6ec0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
6ed0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
6ee0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
6ef0: 52 65 67 69 73 74 65 72 65 64 20 76 66 73 20 6d  Registered vfs m
6f00: 6f 64 75 6c 65 73 20 61 72 65 20 6b 65 70 74 20  odules are kept 
6f10: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
6f20: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
6f30: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
6f40: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
6f50: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
6f60: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
6f70: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
6f80: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
6f90: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
6fa0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
6fb0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
6fc0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
6fd0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
6fe0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a  rches the list..
6ff0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
7000: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
7010: 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65 20  y fields in the 
7020: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
7030: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7040: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7050: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7060: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7070: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7080: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7090: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
70a0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
70b0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
70c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
70d0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
70e0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
70f0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
7100: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7110: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7120: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7130: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7140: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7150: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7160: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7170: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7180: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7190: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
71a0: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
71b0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
71c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
71d0: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
71e0: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
71f0: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
7200: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
7210: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
7220: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
7230: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
7240: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7250: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7260: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
7270: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
7280: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
7290: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
72a0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
72b0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
72c0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
72d0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
72e0: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
72f0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
7300: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
7310: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
7320: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
7330: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7340: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7350: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7360: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7370: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7380: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7390: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
73a0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
73b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
73c0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
73d0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
73e0: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
73f0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
7400: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
7410: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
7420: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
7430: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
7440: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7450: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7460: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
7470: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
7480: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
7490: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
74a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
74b0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
74c0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
74d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
74e0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
74f0: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
7500: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7510: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
7520: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7530: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
7540: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7550: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7560: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7570: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7580: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7590: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
75a0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
75b0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
75c0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
75d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
75e0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
75f0: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
7600: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
7610: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
7620: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
7630: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
7640: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7650: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7660: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7670: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7680: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7690: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
76a0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
76b0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c 20  ry or rollback, 
76c0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
76d0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
76e0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
76f0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
7700: 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a 2a  s journal are.**
7710: 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20 20   also a no-op.  
7720: 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  Any attempt to r
7730: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
7740: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49 4f  return SQLITE_IO
7750: 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20 69  ERR..** Or the i
7760: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
7770: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
7780: 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  e a database fil
7790: 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f 69  e will.** be doi
77a0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
77b0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
77c0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
77d0: 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e 64  dom order.** and
77e0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
77f0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
7800: 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  ingly..** .** SQ
7810: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
7820: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
7830: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
7840: 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 6d  o the xOpen.** m
7850: 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ethod:.** .** <u
7860: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7870: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7880: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
7890: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
78a0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
78b0: 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d 20  ** .** {F11145} 
78c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
78d0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
78e0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
78f0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
7900: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
7910: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31   is closed.  {F1
7920: 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54  1146} The [SQLIT
7930: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7940: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
7950: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
7960: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
7970: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
7980: 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31 31  urnals. .** {F11
7990: 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  147} The [SQLITE
79a0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
79b0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
79c0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
79d0: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63  pened.** for exc
79e0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
79f0: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
7a00: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
7a10: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65  xcept.** for the
7a20: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
7a30: 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a  ile. {END}.** .*
7a40: 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c 65  * {F11148} At le
7a50: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
7a60: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 69 73 20  es of memory is 
7a70: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
7a80: 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  ite .** to hold 
7a90: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
7aa0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
7ab0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
7ac0: 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  d .** argument t
7ad0: 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44 7d 20  o xOpen.  {END} 
7ae0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
7af0: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
7b00: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
7b10: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
7b20: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
7b30: 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a 2a 20  l it in..** .** 
7b40: 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66 6c 61  {F11149} The fla
7b50: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7b60: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
7b70: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
7b80: 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20 74 65  XISTS] .** to te
7b90: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
7ba0: 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 0a  ance of a file,.
7bb0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  ** or [SQLITE_AC
7bc0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
7bd0: 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 0a 2a  to test to see.*
7be0: 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 72  * if a file is r
7bf0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
7c00: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
7c10: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
7c20: 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 20   to test to see 
7c30: 69 66 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  if a file is at 
7c40: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
7c50: 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c 65 20   {END} The file 
7c60: 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72  can be a .** dir
7c70: 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 7b  ectory..** .** {
7c80: 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77  F11150} SQLite w
7c90: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
7ca0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
7cb0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66  athname+1 byte f
7cc0: 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74  or.** the output
7cd0: 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 47 65   buffers for xGe
7ce0: 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64 20 78 46  tTempname and xF
7cf0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 46 31  ullPathname. {F1
7d00: 31 31 35 31 7d 20 54 68 65 20 65 78 61 63 74 0a  1151} The exact.
7d10: 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ** size of the o
7d20: 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73 20  utput buffer is 
7d30: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
7d40: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
7d50: 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20  th .** methods. 
7d60: 7b 45 4e 44 7d 20 49 66 20 74 68 65 20 6f 75 74  {END} If the out
7d70: 70 75 74 20 62 75 66 66 65 72 20 69 73 20 6e 6f  put buffer is no
7d80: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
7d90: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 0a  SQLITE_CANTOPEN.
7da0: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
7db0: 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20 69  urned. As this i
7dc0: 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  s handled as a f
7dd0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
7de0: 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d 70  Lite,.** vfs imp
7df0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
7e00: 75 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 6f 20  uld endeavor to 
7e10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
7e20: 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50 61  setting .** mxPa
7e30: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
7e40: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
7e50: 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  alue..** .** The
7e60: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
7e70: 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43  xSleep(), and xC
7e80: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74  urrentTime() int
7e90: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
7ea0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
7eb0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
7ec0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
7ed0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
7ee0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
7ef0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
7f00: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
7f10: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
7f20: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
7f30: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
7f40: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
7f50: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
7f60: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
7f70: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
7f80: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
7f90: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
7fa0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
7fb0: 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20  tained.  The.** 
7fc0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
7fd0: 63 61 75 73 65 20 74 68 65 20 63 61 6c 6c 69 6e  cause the callin
7fe0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
7ff0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
8000: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
8010: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
8020: 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e  en.  The xCurren
8030: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
8040: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
8050: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
8060: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
8070: 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a  te and.** time..
8080: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
8090: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
80a0: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
80b0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
80c0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
80d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
80e0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
80f0: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
8100: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
8110: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
8120: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
8130: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
8140: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
8150: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
8160: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
8170: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
8180: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
8190: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
81a0: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
81b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
81c0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
81d0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
81e0: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
81f0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
8200: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
8210: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
8220: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
8230: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
8240: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8250: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8260: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
8270: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
8280: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
8290: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
82a0: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
82b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
82c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
82d0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
82e0: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
82f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8300: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8310: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8320: 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 6e 61  int (*xGetTempna
8330: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8340: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
8350: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
8360: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
8370: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8380: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8390: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
83a0: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
83b0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
83c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
83d0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
83e0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
83f0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
8400: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
8410: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
8420: 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73  oid *(*xDlSym)(s
8430: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
8440: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8450: 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20  Symbol);.  void 
8460: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
8470: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
8480: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
8490: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
84a0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
84b0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
84c0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
84d0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
84e0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
84f0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
8500: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8510: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a  , double*);.  /*
8520: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
8530: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
8540: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
8550: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
8560: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
8570: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
8580: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a   this happens. *
8590: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
85a0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
85b0: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
85c0: 6d 65 74 68 6f 64 20 7b 46 31 31 31 39 30 7d 0a  method {F11190}.
85d0: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39 31 7d 20 54  **.** {F11191} T
85e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
85f0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
8600: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
8610: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8620: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8630: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
8640: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b  3_vfs] object. {
8650: 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65 72  END}  They deter
8660: 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e 64  mine.** the kind
8670: 20 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f 66   of what kind of
8680: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
8690: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
86a0: 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f  is.** looking fo
86b0: 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69 74  r.  {F11192} Wit
86c0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
86d0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
86e0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
86f0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
8700: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
8710: 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d 20  xists. {F11193} 
8720: 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41  With.** SQLITE_A
8730: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
8740: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8750: 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65  hod checks to se
8760: 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  e.** if the file
8770: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
8780: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20  e and writable. 
8790: 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a 2a   {F11194} With.*
87a0: 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  * SQLITE_ACCESS_
87b0: 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73 73  READ the xAccess
87c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
87d0: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
87e0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
87f0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8800: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8810: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8820: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8830: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8840: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8850: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8860: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
8870: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
8880: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
8890: 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a  des {F12200}.**.
88a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
88b0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
88c0: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
88d0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
88e0: 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  es the.** [SQLIT
88f0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
8900: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
8910: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
8920: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65 20   SQLite..** The 
8930: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8940: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
8950: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
8960: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
8970: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
8980: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
8990: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20  .**.** {F12201} 
89a0: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  Each new [databa
89b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
89c0: 61 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  as the .**      
89d0: 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65      [extended re
89e0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
89f0: 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
8a00: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
8a10: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ult..**.** {F122
8a20: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
8a30: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
8a40: 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74  _codes(D,F)] int
8a50: 65 72 66 61 63 65 20 77 69 6c 6c 20 65 6e 61 62  erface will enab
8a60: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
8a70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8a80: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 0a  codes] for the .
8a90: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
8aa0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8ab0: 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61 72  ] D if the F par
8ac0: 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
8ad0: 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64     is true, or d
8ae0: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46  isable them if F
8af0: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
8b00: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
8b10: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
8b20: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
8b30: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
8b40: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
8b50: 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30  rt Rowid {F12220
8b60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  }.**.** Each ent
8b70: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
8b80: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
8b90: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
8ba0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
8bb0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
8bc0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
8bd0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
8be0: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
8bf0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
8c00: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
8c10: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
8c20: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
8c30: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
8c40: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
8c50: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
8c60: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
8c70: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
8c80: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
8c90: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
8ca0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
8cb0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6e  ** is another an
8cc0: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
8cd0: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
8ce0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8cf0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
8d00: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
8d10: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
8d20: 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  RT into the data
8d30: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61  base from the da
8d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8d50: 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68  n.** shown in th
8d60: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
8d70: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
8d80: 66 75 6c 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68  ful inserts.** h
8d90: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
8da0: 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61  d on this databa
8db0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
8dc0: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
8dd0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53  .**.** If an INS
8de0: 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69  ERT occurs withi
8df0: 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
8e00: 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  n the rowid of t
8e10: 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72  he.** inserted r
8e20: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
8e30: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
8e40: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
8e50: 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e  igger.** is runn
8e60: 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74  ing.  But once t
8e70: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
8e80: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
8e90: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
8ea0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
8eb0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
8ec0: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
8ed0: 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72  before the.** tr
8ee0: 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
8ef0: 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61  ** An INSERT tha
8f00: 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
8f10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
8f20: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
8f30: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73  * successful ins
8f40: 65 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ert and does not
8f50: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
8f60: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
8f70: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
8f80: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
8f90: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
8fa0: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
8fb0: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
8fc0: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
8fd0: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
8fe0: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
8ff0: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
9000: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
9010: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
9020: 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52  ils.  When INSER
9030: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a  T OR REPLACE .**
9040: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
9050: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
9060: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
9070: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
9080: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
9090: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
90a0: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
90b0: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
90c0: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
90d0: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
90e0: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
90f0: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
9100: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
9110: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
9120: 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72  face. .**.** For
9130: 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
9140: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
9150: 6e 20 69 6e 73 65 72 74 20 69 73 20 63 6f 6e 73  n insert is cons
9160: 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
9170: 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
9180: 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
9190: 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
91a0: 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  k..**.** INVARIA
91b0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
91c0: 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
91d0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
91e0: 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  id()] function r
91f0: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
9200: 20 20 20 20 20 20 20 72 6f 77 69 64 20 6f 66 20         rowid of 
9210: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
9220: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72  successful inser
9230: 74 20 64 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20  t done.**       
9240: 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64     on the same d
9250: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9260: 6f 6e 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68  on and within th
9270: 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
9280: 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
9290: 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
92a0: 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20  here have.**    
92b0: 20 20 20 20 20 20 62 65 65 6e 20 6e 6f 20 71 75        been no qu
92c0: 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73  alifying inserts
92d0: 20 6f 6e 20 74 68 61 74 20 63 6f 6e 6e 65 63 74   on that connect
92e0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ion..**.** {F122
92f0: 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
9300: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
9310: 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  id()] function r
9320: 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
9330: 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68     same value wh
9340: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
9350: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20  he same trigger 
9360: 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
9370: 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20      immediately 
9380: 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72  before and after
9390: 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a   a ROLLBACK..**.
93a0: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
93b0: 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d 20 49  **.** {U12232} I
93c0: 66 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  f separate threa
93d0: 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73  d does a new ins
93e0: 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  ert on the same.
93f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
9400: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
9410: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
9420: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
9430: 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20  owid()].**      
9440: 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20      function is 
9450: 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
9460: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
9470: 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a  t insert rowid,.
9480: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
9490: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
94a0: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
94b0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
94c0: 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  d()] is.**      
94d0: 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c      unpredictabl
94e0: 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
94f0: 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
9500: 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
9510: 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74  **          last
9520: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a   insert rowid..*
9530: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
9540: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
9550: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
9560: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
9570: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
9580: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
9590: 6f 64 69 66 69 65 64 20 7b 46 31 32 32 34 30 7d  odified {F12240}
95a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
95b0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
95c0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
95d0: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
95e0: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
95f0: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
9600: 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
9610: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
9620: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
9630: 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6e 6e  t.** on the conn
9640: 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
9650: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
9660: 72 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a  rameter.  Only.*
9670: 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  * changes that a
9680: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
9690: 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53  ified by the INS
96a0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a  ERT, UPDATE, or.
96b0: 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
96c0: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
96d0: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
96e0: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
96f0: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
9700: 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74  t counted. Use t
9710: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
9720: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
9730: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
9740: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
9750: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
9760: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
9770: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
9780: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20  s..**.** A "row 
9790: 63 68 61 6e 67 65 73 22 20 69 73 20 61 20 63 68  changes" is a ch
97a0: 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
97b0: 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
97c0: 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
97d0: 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
97e0: 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
97f0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
9800: 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
9810: 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
9820: 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45  fects of REPLACE
9830: 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
9840: 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
9850: 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
9860: 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c  ssing, DROP TABL
9870: 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  E, or by any oth
9880: 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
9890: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
98a0: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
98b0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  ges..**.** A "tr
98c0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
98d0: 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
98e0: 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
98f0: 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
9900: 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
9910: 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f  f a trigger.  Mo
9920: 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
9930: 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
9940: 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
9950: 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
9960: 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
9970: 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
9980: 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
9990: 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
99a0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
99b0: 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
99c0: 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
99d0: 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
99e0: 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
99f0: 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
9a00: 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
9a10: 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
9a20: 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
9a30: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b  .**.** Calling [
9a40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
9a50: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
9a60: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
9a70: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
9a80: 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
9a90: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
9aa0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
9ab0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
9ac0: 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
9ad0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
9ae0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
9af0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
9b00: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
9b10: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9b20: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
9b30: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68  ext..**.** So wh
9b40: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
9b50: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
9b60: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
9b70: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
9b80: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
9b90: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
9ba0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
9bb0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
9bc0: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
9bd0: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
9be0: 2e 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20  ..** Within the 
9bf0: 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
9c00: 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  r, the sqlite3_c
9c10: 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
9c20: 63 65 0a 2a 2a 20 63 61 6e 20 62 65 20 63 61 6c  ce.** can be cal
9c30: 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
9c40: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
9c50: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
9c60: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
9c70: 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
9c80: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
9c90: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
9ca0: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
9cb0: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
9cc0: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
9cd0: 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
9ce0: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
9cf0: 20 69 6e 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63   in changes.** c
9d00: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
9d10: 67 65 72 73 20 73 69 6e 63 65 20 74 68 65 79 20  gers since they 
9d20: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
9d30: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
9d40: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
9d50: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
9d60: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
9d70: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45  without.** a WHE
9d80: 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f  RE clause by dro
9d90: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
9da0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
9db0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a   (This is much.*
9dc0: 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  * faster than go
9dd0: 69 6e 67 20 74 68 72 6f 75 67 68 20 61 6e 64 20  ing through and 
9de0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
9df0: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
9e00: 6d 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 29  m the.** table.)
9e10: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69    Because of thi
9e20: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
9e30: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
9e40: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
9e50: 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20   table" are not 
9e60: 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 20  row changes and 
9e70: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
9e80: 74 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 73 71  ted.** by the sq
9e90: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
9ea0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  or [sqlite3_tota
9eb0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
9ec0: 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65  ctions..** To ge
9ed0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
9ee0: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
9ef0: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
9f00: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
9f10: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
9f20: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
9f30: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
9f40: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20  .**.** {F12241} 
9f50: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  The [sqlite3_cha
9f60: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
9f70: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
9f80: 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ber of.**       
9f90: 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63     row changes c
9fa0: 61 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73  aused by the mos
9fb0: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
9fc0: 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20   UPDATE,.**     
9fd0: 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73       or DELETE s
9fe0: 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
9ff0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
a000: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  nnection and.** 
a010: 20 20 20 20 20 20 20 20 20 77 69 74 68 69 6e 20           within 
a020: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
a030: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
a040: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a  o if there have.
a050: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  **          not 
a060: 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79  been any qualify
a070: 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ing row changes.
a080: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
a090: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35  NS:.**.** {U1225
a0a0: 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
a0b0: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
a0c0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
a0d0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
a0e0: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
a0f0: 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33    while [sqlite3
a100: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
a110: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
a120: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
a130: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e  *          is un
a140: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
a150: 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  unmeaningful..*/
a160: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
a170: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
a180: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a190: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
a1a0: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
a1b0: 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54  F12260}.***.** T
a1c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
a1d0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
a1e0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
a1f0: 61 75 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45  aused.** by INSE
a200: 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
a210: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
a220: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
a230: 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73  se handle.** was
a240: 20 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f   opened.  The co
a250: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
a260: 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
a270: 6c 20 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e  l trigger.** con
a280: 74 65 78 74 73 2e 20 20 42 75 74 20 74 68 65 20  texts.  But the 
a290: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
a2a0: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
a2b0: 73 65 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d  sed to.** implem
a2c0: 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73  ent REPLACE cons
a2d0: 74 72 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c  traints, do roll
a2e0: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
a2f0: 72 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72  rocessing,.** or
a300: 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63   DROP table proc
a310: 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63  essing..** The c
a320: 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f  hanges.** are co
a330: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
a340: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
a350: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
a360: 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20  s completed .** 
a370: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
a380: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61  ent handle is pa
a390: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
a3a0: 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a  _reset()] or .**
a3b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
a3c0: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
a3d0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
a3e0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
a3f0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
a400: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45  without.** a WHE
a410: 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f  RE clause by dro
a420: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
a430: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
a440: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a   (This is much.*
a450: 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  * faster than go
a460: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
a470: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
a480: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
a490: 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  form the table.)
a4a0: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20    Because of.** 
a4b0: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
a4c0: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f  n, the change co
a4d0: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20  unt for "DELETE 
a4e0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c  FROM table" will
a4f0: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61   be.** zero rega
a500: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
a510: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
a520: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
a530: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20  nally in the.** 
a540: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e  table. To get an
a550: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
a560: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
a570: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
a580: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
a590: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
a5a0: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
a5b0: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
a5c0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
a5d0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
a5e0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
a5f0: 2a 20 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54  * .** {F12261} T
a600: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
a610: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74  l_changes()] ret
a620: 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
a630: 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
a640: 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73    of row changes
a650: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
a660: 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f  T, UPDATE, and/o
a670: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20  r DELETE.**     
a680: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
a690: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
a6a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
a6b0: 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20  ], in any.**    
a6c0: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
a6d0: 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65  ntext, since the
a6e0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a6f0: 74 69 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20  tion was.**     
a700: 20 20 20 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a       created..**
a710: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
a720: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20  .**.** {U12264} 
a730: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
a740: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
a750: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
a760: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a770: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
a780: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
a790: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
a7a0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
a7b0: 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20 20  he value .**    
a7c0: 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69        returned i
a7d0: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
a7e0: 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 66 75 6c  and unmeaningful
a7f0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a800: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
a810: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
a820: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
a830: 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
a840: 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32 32 37  ing Query {F1227
a850: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0}.**.** This fu
a860: 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
a870: 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
a880: 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
a890: 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
a8a0: 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
a8b0: 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
a8c0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
a8d0: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
a8e0: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
a8f0: 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
a900: 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
a910: 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
a920: 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
a930: 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
a940: 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
a950: 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
a960: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
a970: 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
a980: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
a990: 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
a9a0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
a9b0: 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
a9c0: 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
a9d0: 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
a9e0: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
a9f0: 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
aa00: 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
aa10: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
aa20: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
aa30: 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69  ection that.** i
aa40: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
aa50: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
aa60: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
aa70: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
aa80: 2a 20 49 66 20 61 6e 20 53 51 4c 20 69 73 20 76  * If an SQL is v
aa90: 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
aaa0: 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
aab0: 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 74  when sqlite3_int
aac0: 65 72 72 75 70 74 28 29 0a 2a 2a 20 69 73 20 63  errupt().** is c
aad0: 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
aae0: 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
aaf0: 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20   opportunity to 
ab00: 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 2e 0a  be interrupted..
ab10: 2a 2a 20 49 74 20 6d 69 67 68 74 20 63 6f 6e 74  ** It might cont
ab20: 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
ab30: 6f 6e 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  on..** An SQL op
ab40: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
ab50: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
ab60: 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
ab70: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 20 20  TE_INTERRUPT].  
ab80: 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
ab90: 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
aba0: 20 69 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 52 54   is an.** INSERT
abb0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
abc0: 45 54 45 20 74 68 61 74 20 69 73 20 69 6e 73 69  ETE that is insi
abd0: 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
abe0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20  ransaction, .** 
abf0: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
ac00: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c  transaction will
ac10: 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
ac20: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
ac30: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
ac40: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
ac50: 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
ac60: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
ac70: 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
ac80: 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
ac90: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
aca0: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  turns..**.** INV
acb0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
acc0: 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c  F12271} The [sql
acd0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ace0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
acf0: 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69   force all runni
ad00: 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ng.**          S
ad10: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  QL statements as
ad20: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
ad30: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
ad40: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
ad50: 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61         to halt a
ad60: 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20  fter processing 
ad70: 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69  at most one addi
ad80: 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a  tional row of.**
ad90: 20 20 20 20 20 20 20 20 20 20 64 61 74 61 2e 0a            data..
ada0: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41  **.** {F12272} A
adb0: 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
adc0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
add0: 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  pted by [sqlite3
ade0: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
adf0: 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72            will r
ae00: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
ae10: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20  TERRUPT]..**.** 
ae20: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
ae30: 2a 2a 20 7b 55 31 32 32 37 39 7d 20 49 66 20 74  ** {U12279} If t
ae40: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
ae50: 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
ae60: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
ae70: 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
ae80: 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67        is running
ae90: 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
aea0: 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
aeb0: 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
aec0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
aed0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
aee0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
aef0: 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
af00: 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
af10: 6c 65 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a  lete {F10510}.**
af20: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
af30: 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  es are useful fo
af40: 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  r command-line i
af50: 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
af60: 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
af70: 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
af80: 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
af90: 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20   complete a SQL 
afa0: 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
afb0: 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
afc0: 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
afd0: 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
afe0: 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
aff0: 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
b000: 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
b010: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  s return true if
b020: 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
b030: 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
b040: 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
b050: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20  L statement.  A 
b060: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
b070: 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
b080: 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
b090: 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
b0a0: 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
b0b0: 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66  ot a fragment of
b0c0: 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49   a.** CREATE TRI
b0d0: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
b0e0: 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74   Semicolons that
b0f0: 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
b100: 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
b110: 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
b120: 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
b130: 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
b140: 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
b150: 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
b160: 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
b170: 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
b180: 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
b190: 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
b1a0: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
b1b0: 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
b1c0: 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
b1d0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
b1e0: 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
b1f0: 51 4c 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c  QL and.** so wil
b200: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
b210: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
b220: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
b230: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
b240: 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73  * {F10511} The s
b250: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
b260: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
b270: 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74  mplete16() funct
b280: 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ions.**         
b290: 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f   return true (no
b2a0: 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f  n-zero) if and o
b2b0: 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 0a  nly if the last.
b2c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d  **          non-
b2d0: 77 68 69 74 65 73 70 61 63 65 20 74 6f 6b 65 6e  whitespace token
b2e0: 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20   in their input 
b2f0: 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  is a semicolon t
b300: 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
b310: 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
b320: 6e 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20  n the BEGIN and 
b330: 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20  END of a CREATE 
b340: 54 52 49 47 47 45 52 0a 2a 2a 20 20 20 20 20 20  TRIGGER.**      
b350: 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
b360: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
b370: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32 7d  :.**.** {U10512}
b380: 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71   The input to sq
b390: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
b3a0: 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
b3b0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
b3c0: 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
b3d0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35  ing..**.** {U105
b3e0: 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  13} The input to
b3f0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
b400: 65 31 36 28 29 20 6d 75 73 74 20 62 65 20 61 20  e16() must be a 
b410: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
b420: 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
b430: 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
b440: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
b450: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
b460: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
b470: 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
b480: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
b490: 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
b4a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b4b0: 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
b4c0: 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
b4d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
b4e0: 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a  rors {F12310}.**
b4f0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
b500: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61   identifies a ca
b510: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
b520: 74 68 61 74 20 6d 69 67 68 74 20 62 65 0a 2a 2a  that might be.**
b530: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
b540: 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  r an attempt is 
b550: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
b560: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a  atabase table .*
b570: 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  * that another t
b580: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
b590: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20   has locked..** 
b5a0: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
b5b0: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
b5c0: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
b5d0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
b5e0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
b5f0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
b600: 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
b610: 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
b620: 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62  ock..** If the b
b630: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
b640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
b650: 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77  he.** callback w
b660: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
b670: 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
b680: 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 74  s.  The.** first
b690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b6a0: 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
b6b0: 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
b6c0: 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
b6d0: 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
b6e0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 72  gument to this r
b6f0: 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65 63  outine.  The sec
b700: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
b710: 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69  ** the handler i
b720: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
b730: 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
b740: 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
b750: 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
b760: 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
b770: 20 65 76 65 6e 74 2e 20 20 20 49 66 20 74 68 65   event.   If the
b780: 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
b790: 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
b7a0: 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
b7b0: 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
b7c0: 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
b7d0: 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
b7e0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
b7f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
b800: 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
b810: 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
b820: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
b830: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
b840: 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
b850: 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
b860: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b870: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
b880: 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
b890: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
b8a0: 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
b8b0: 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
b8c0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a  guarantee that.*
b8d0: 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  * it will be inv
b8e0: 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65 20  oked when there 
b8f0: 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
b900: 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  on..** If SQLite
b910: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
b920: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
b930: 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  sy handler could
b940: 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20   result in.** a 
b950: 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
b960: 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
b970: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
b980: 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  SY] or.** [SQLIT
b990: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
b9a0: 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
b9b0: 6b 69 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73 79  king the.** busy
b9c0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
b9d0: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
b9e0: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
b9f0: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
ba00: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
ba10: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
ba20: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
ba30: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
ba40: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
ba50: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
ba60: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
ba70: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
ba80: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
ba90: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
baa0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
bab0: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
bac0: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
bad0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
bae0: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
baf0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
bb00: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
bb10: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
bb20: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
bb30: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
bb40: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
bb50: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
bb60: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
bb70: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
bb80: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
bb90: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
bba0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
bbb0: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
bbc0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
bbd0: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
bbe0: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
bbf0: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
bc00: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
bc10: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
bc20: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
bc30: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
bc40: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
bc50: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
bc60: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
bc70: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
bc80: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
bc90: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
bca0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
bcb0: 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
bcc0: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
bcd0: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
bce0: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
bcf0: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
bd00: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
bd10: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
bd20: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
bd30: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
bd40: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
bd50: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
bd60: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
bd70: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
bd80: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
bd90: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
bda0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
bdb0: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
bdc0: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
bdd0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
bde0: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
bdf0: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
be00: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
be10: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
be20: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
be30: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
be40: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
be50: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
be60: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
be70: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
be80: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
be90: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
bea0: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
beb0: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
bec0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
bed0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
bee0: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
bef0: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
bf00: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
bf10: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
bf20: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
bf30: 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
bf40: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
bf50: 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74  .sqlite.org/cvst
bf60: 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
bf70: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
bf80: 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
bf90: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
bfa0: 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
bfb0: 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
bfc0: 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
bfd0: 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
bfe0: 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65  tant..**..** The
bff0: 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
c000: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
c010: 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
c020: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a   each database.*
c030: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
c040: 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
c050: 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
c060: 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e   any previous on
c070: 65 2e 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  e. .** Note that
c080: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
c090: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
c0a0: 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  ] will also set 
c0b0: 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20  or clear.** the 
c0c0: 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
c0d0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
c0e0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54  **.** {F12311} T
c0f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
c100: 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63  _handler()] func
c110: 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
c120: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  e busy handler.*
c130: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
c140: 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74 61 62  ack in the datab
c150: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
c160: 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
c170: 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   1st.**         
c180: 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
c190: 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
c1a0: 65 72 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  er identified by
c1b0: 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33 72 64   the 2nd and 3rd
c1c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
c1d0: 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ameters..**.** {
c1e0: 46 31 32 33 31 32 7d 20 54 68 65 20 64 65 66 61  F12312} The defa
c1f0: 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  ult busy handler
c200: 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73   for new databas
c210: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73  e connections is
c220: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   NULL..**.** {F1
c230: 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f  2314} When two o
c240: 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73 65 20  r more database 
c250: 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72 65  connection share
c260: 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 2c   a common cache,
c270: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
c280: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
c290: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
c2a0: 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e  onnection curren
c2b0: 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  tly using.**    
c2c0: 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20        the cache 
c2d0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
c2e0: 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e  the cache encoun
c2f0: 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a  ters a lock..**.
c300: 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61  ** {F12316} If a
c310: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
c320: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a  llback returns z
c330: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ero, then the SQ
c340: 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  Lite.**         
c350: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
c360: 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63  provoked the loc
c370: 6b 69 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c 20  king event will 
c380: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
c390: 20 20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d     [SQLITE_BUSY]
c3a0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d  ..**.** {F12318}
c3b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
c3c0: 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 68 61  okes the busy ha
c3d0: 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61  ndler with two a
c3e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
c3f0: 20 20 20 20 20 20 20 20 20 20 61 72 65 20 61 20            are a 
c400: 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e  copy of the poin
c410: 74 65 72 20 73 75 70 70 6c 69 65 64 20 62 79 20  ter supplied by 
c420: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
c430: 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
c440: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
c450: 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20  andler()] and a 
c460: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
c470: 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20  ber of prior.** 
c480: 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
c490: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79  ions of the busy
c4a0: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65   handler for the
c4b0: 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
c4c0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ent..**.** LIMIT
c4d0: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
c4e0: 31 32 33 31 39 7d 20 41 20 62 75 73 79 20 68 61  12319} A busy ha
c4f0: 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74  ndler should not
c500: 20 63 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 20   call close the 
c510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c520: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
c530: 6f 72 20 70 72 65 70 61 72 65 64 20 73 74 61 74  or prepared stat
c540: 65 6d 65 6e 74 20 74 68 61 74 20 69 6e 76 6f 6b  ement that invok
c550: 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
c560: 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
c570: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
c580: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
c590: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
c5a0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
c5b0: 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
c5c0: 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34  y Timeout {F1234
c5d0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
c5e0: 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
c5f0: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
c600: 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
c610: 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c 65 65 70  r].** that sleep
c620: 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68  s for a while wh
c630: 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73  en a.** table is
c640: 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61   locked.  The ha
c650: 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70  ndler will sleep
c660: 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
c670: 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61  until .** at lea
c680: 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
c690: 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
c6a0: 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e   have been done.
c6b0: 20 7b 46 31 32 33 34 33 7d 20 41 66 74 65 72 0a   {F12343} After.
c6c0: 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  ** "ms" millisec
c6d0: 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
c6e0: 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  , the handler re
c6f0: 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a  turns 0 which.**
c700: 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
c710: 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
c720: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
c730: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
c740: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
c750: 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  * Calling this r
c760: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
c770: 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
c780: 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
c790: 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
c7a0: 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
c7b0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  s..**.** There c
c7c0: 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
c7d0: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
c7e0: 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
c7f0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
c800: 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e  nnection.  If an
c810: 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
c820: 65 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  er was defined  
c830: 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  .** (using [sqli
c840: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
c850: 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
c860: 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
c870: 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
c880: 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
c890: 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a  s cleared..**.**
c8a0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
c8b0: 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68 65 20  ** {F12341} The 
c8c0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
c8d0: 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f  meout()] functio
c8e0: 6e 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  n overrides any 
c8f0: 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
c900: 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
c910: 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73  timeout()] or [s
c920: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
c930: 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a  ler()] setting.*
c940: 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
c950: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
c960: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
c970: 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20 74 68  * {F12343} If th
c980: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
c990: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
c9a0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c  _timeout()] is l
c9b0: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
c9c0: 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f       or equal to
c9d0: 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
c9e0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
c9f0: 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a  cleared so that.
ca00: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20  **          all 
ca10: 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69  subsequent locki
ca20: 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69  ng events immedi
ca30: 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51  ately return [SQ
ca40: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
ca50: 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20 74 68  * {F12344} If th
ca60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
ca70: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
ca80: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61  _timeout()] is a
ca90: 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20   positive.**    
caa0: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20        number N, 
cab0: 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64  then a busy hand
cac0: 6c 65 72 20 69 73 20 73 65 74 20 74 68 61 74 20  ler is set that 
cad0: 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73  repeatedly calls
cae0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
caf0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
cb00: 20 69 6e 20 74 68 65 20 56 46 53 20 69 6e 74 65   in the VFS inte
cb10: 72 66 61 63 65 20 75 6e 74 69 6c 20 65 69 74 68  rface until eith
cb20: 65 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  er the.**       
cb30: 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f     lock clears o
cb40: 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75  r until the cumu
cb50: 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d  lative sleep tim
cb60: 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 0a  e reported back.
cb70: 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 78  **          by x
cb80: 53 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20  Sleep() exceeds 
cb90: 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  N milliseconds..
cba0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
cbb0: 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
cbc0: 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
cbd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
cbe0: 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
cbf0: 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
cc00: 20 51 75 65 72 69 65 73 20 7b 46 31 32 33 37 30   Queries {F12370
cc10: 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  }.**.** Definiti
cc20: 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
cc30: 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
cc40: 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
cc50: 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
cc60: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
cc70: 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
cc80: 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
cc90: 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
cca0: 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
ccb0: 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
ccc0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
ccd0: 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
cce0: 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
ccf0: 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
cd00: 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
cd10: 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
cd20: 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
cd30: 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
cd40: 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
cd50: 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
cd60: 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
cd70: 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
cd80: 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
cd90: 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
cda0: 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
cdb0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
cdc0: 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
cdd0: 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
cde0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
cdf0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
ce00: 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  * UTF-8 strings.
ce10: 20 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31    There are (N+1
ce20: 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
ce30: 74 68 65 20 61 72 72 61 79 2e 20 20 0a 2a 2a 20  the array.  .** 
ce40: 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
ce50: 74 65 72 73 20 70 6f 69 6e 74 20 74 6f 20 7a 65  ters point to ze
ce60: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
ce70: 72 69 6e 67 73 20 74 68 61 74 20 0a 2a 2a 20 63  rings that .** c
ce80: 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
ce90: 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
cea0: 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
ceb0: 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
cec0: 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
ced0: 75 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76  ults.  NULL.** v
cee0: 61 6c 75 65 73 20 61 72 65 20 67 69 76 65 20 61  alues are give a
cef0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
cf00: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
cf10: 20 61 72 65 20 69 6e 0a 2a 2a 20 74 68 65 69 72   are in.** their
cf20: 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
cf30: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 72 65  inated string re
cf40: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
cf50: 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
cf60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
cf70: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
cf80: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
cf90: 68 74 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 6f  ht consists of o
cfa0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
cfb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
cfc0: 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
cfd0: 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
cfe0: 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
cff0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
d000: 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
d010: 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
d020: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
d030: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
d040: 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
d050: 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
d060: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
d070: 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
d080: 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
d090: 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
d0a0: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
d0b0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
d0c0: 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
d0d0: 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
d0e0: 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
d0f0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
d100: 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
d110: 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
d120: 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
d130: 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
d140: 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
d150: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
d160: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
d170: 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
d180: 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
d190: 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
d1a0: 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
d1b0: 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
d1c0: 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
d1d0: 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
d1e0: 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
d1f0: 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
d200: 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
d210: 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
d220: 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
d230: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
d240: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
d250: 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
d260: 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
d270: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
d280: 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
d290: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
d2a0: 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
d2b0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d2c0: 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
d2d0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d2e0: 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
d2f0: 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
d300: 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
d310: 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
d320: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
d330: 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
d340: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d350: 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
d360: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
d370: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te>.**.** The sq
d380: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d390: 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
d3a0: 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
d3b0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
d3c0: 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
d3d0: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
d3e0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
d3f0: 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
d400: 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
d410: 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  er.  It returns 
d420: 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
d430: 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
d440: 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
d450: 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
d460: 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c  ** After the cal
d470: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61  ling function ha
d480: 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
d490: 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20   the result, it 
d4a0: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20  should .** pass 
d4b0: 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
d4c0: 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
d4d0: 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
d4e0: 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
d4f0: 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20   to .** release 
d500: 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
d510: 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20  was malloc-ed.  
d520: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
d530: 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ay the .** [sqli
d540: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
d550: 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
d560: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
d570: 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
d580: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
d590: 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
d5a0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
d5b0: 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20  directly.  Only 
d5c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
d5d0: 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
d5e0: 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
d5f0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
d600: 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
d610: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d620: 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
d630: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
d640: 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
d650: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
d660: 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
d670: 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
d680: 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
d690: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
d6a0: 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
d6b0: 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
d6c0: 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
d6d0: 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
d6e0: 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
d6f0: 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
d700: 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
d710: 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
d720: 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
d730: 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
d740: 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
d750: 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
d760: 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
d770: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
d780: 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
d790: 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
d7a0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
d7b0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
d7c0: 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
d7d0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
d7e0: 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49 66 20 61  ** {F12371} If a
d7f0: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
d800: 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d  ble()] fails a m
d810: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d820: 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
d830: 20 20 20 69 74 20 66 72 65 65 73 20 74 68 65 20     it frees the 
d840: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64  result table und
d850: 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c  er construction,
d860: 20 61 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20 20   aborts the.**  
d870: 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69 6e          query in
d880: 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 73 20   process, skips 
d890: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71  any subsequent q
d8a0: 75 65 72 69 65 73 2c 20 73 65 74 73 20 74 68 65  ueries, sets the
d8b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 72 65  .**          *re
d8c0: 73 75 6c 74 70 20 6f 75 74 70 75 74 20 70 6f 69  sultp output poi
d8d0: 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64  nter to NULL and
d8e0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
d8f0: 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _NOMEM]..**.** {
d900: 46 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 6e  F12373} If the n
d910: 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72  column parameter
d920: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
d930: 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
d940: 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
d950: 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
d960: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69  get_table()] wri
d970: 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  te the number of
d980: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
d990: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
d9a0: 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
d9b0: 65 72 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d  ery into *ncolum
d9c0: 6e 20 69 66 20 74 68 65 20 71 75 65 72 79 20 69  n if the query i
d9d0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75  s.**          su
d9e0: 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 68 65  ccessful (if the
d9f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
da00: 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a  s SQLITE_OK)..**
da10: 0a 2a 2a 20 7b 46 31 32 33 37 34 7d 20 49 66 20  .** {F12374} If 
da20: 74 68 65 20 6e 72 6f 77 20 70 61 72 61 6d 65 74  the nrow paramet
da30: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67  er to [sqlite3_g
da40: 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e  et_table()] is n
da50: 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  ot NULL.**      
da60: 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
da70: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77  3_get_table()] w
da80: 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20  rite the number 
da90: 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a  of rows in the.*
daa0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
dab0: 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
dac0: 72 79 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69 66  ry into *nrow if
dad0: 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a   the query is.**
dae0: 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65 73            succes
daf0: 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e  sful (if the fun
db00: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51  ction returns SQ
db10: 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK)..**.** 
db20: 7b 46 31 32 33 37 36 7d 20 54 68 65 20 5b 73 71  {F12376} The [sq
db30: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
db40: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  )] function sets
db50: 20 69 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61   its *ncolumn va
db60: 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
db70: 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
db80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
db90: 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
dba0: 65 20 71 75 65 72 79 20 69 6e 20 74 68 65 0a 2a  e query in the.*
dbb0: 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 20 70  *          sql p
dbc0: 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f 20  arameter, or to 
dbd0: 7a 65 72 6f 20 69 66 20 74 68 65 20 71 75 65 72  zero if the quer
dbe0: 79 20 69 6e 20 73 71 6c 20 68 61 73 20 61 6e 20  y in sql has an 
dbf0: 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20  empty.**        
dc00: 20 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f    result set..*/
dc10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
dc20: 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
dc30: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
dc40: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
dc50: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
dc60: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f  har *sql,      /
dc70: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
dc80: 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
dc90: 2a 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20 20 20  ***pResult,     
dca0: 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
dcb0: 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
dcc0: 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20  t *nrow,        
dcd0: 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
dce0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
dcf0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
dd00: 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20  nt *ncolumn,    
dd10: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
dd20: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
dd30: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
dd40: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
dd50: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
dd60: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
dd70: 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
dd80: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
dd90: 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
dda0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ddb0: 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
ddc0: 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
ddd0: 74 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a  tions {F17400}.*
dde0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
ddf0: 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b  nes are workalik
de00: 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
de10: 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
de20: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
de30: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
de40: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  library..**.** T
de50: 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
de60: 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
de70: 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
de80: 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
de90: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
dea0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
deb0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
dec0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
ded0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
dee0: 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
def0: 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
df00: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
df10: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
df20: 5d 2e 20 20 20 42 6f 74 68 20 72 6f 75 74 69 6e  ].   Both routin
df30: 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
df40: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
df50: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
df60: 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
df70: 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
df80: 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
df90: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
dfa0: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  tring..**.** In 
dfb0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
dfc0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
dfd0: 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
dfe0: 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
dff0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
e000: 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
e010: 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
e020: 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
e030: 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
e040: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
e050: 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
e060: 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
e070: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
e080: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
e090: 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
e0a0: 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
e0b0: 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
e0c0: 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20  rom snprintf(). 
e0d0: 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
e0e0: 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
e0f0: 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
e100: 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
e110: 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
e120: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
e130: 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20  ity.  Note also 
e140: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
e150: 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
e160: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
e170: 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
e180: 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
e190: 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
e1a0: 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
e1b0: 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
e1c0: 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68  er.  We admit th
e1d0: 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
e1e0: 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
e1f0: 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
e200: 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
e210: 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
e220: 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
e230: 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
e240: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
e250: 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
e260: 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
e270: 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
e280: 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  y..**.** As long
e290: 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
e2a0: 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
e2b0: 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
e2c0: 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
e2d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
e2e0: 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
e2f0: 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
e300: 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74  ated.  The first
e310: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
e320: 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
e330: 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
e340: 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
e350: 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
e360: 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
e370: 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
e380: 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
e390: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
e3a0: 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
e3b0: 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
e3c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
e3d0: 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
e3e0: 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
e3f0: 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
e400: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
e410: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
e420: 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
e430: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
e440: 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
e450: 69 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20  intf formatting 
e460: 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
e470: 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
e480: 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
e490: 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
e4a0: 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
e4b0: 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
e4c0: 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
e4d0: 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
e4e0: 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
e4f0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
e500: 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
e510: 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
e520: 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
e530: 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
e540: 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
e550: 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
e560: 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
e570: 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
e580: 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
e590: 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
e5a0: 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
e5b0: 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
e5c0: 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
e5d0: 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
e5e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
e5f0: 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20  xample, so some 
e600: 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
e610: 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
e620: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
e630: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
e640: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
e650: 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
e660: 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
e670: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
e680: 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
e690: 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
e6a0: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
e6b0: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
e6c0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
e6d0: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
e6e0: 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
e6f0: 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
e700: 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
e710: 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
e720: 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
e730: 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
e740: 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
e750: 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
e760: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
e770: 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
e780: 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
e790: 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
e7a0: 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
e7b0: 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
e7c0: 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
e7d0: 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
e7e0: 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
e7f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
e800: 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
e810: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
e820: 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
e830: 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
e840: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
e850: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
e860: 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
e870: 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
e880: 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
e890: 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
e8a0: 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
e8b0: 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
e8c0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
e8d0: 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
e8e0: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
e8f0: 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
e900: 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
e910: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
e920: 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
e930: 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
e940: 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
e950: 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
e960: 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61   you.** should a
e970: 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
e980: 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
e990: 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
e9a0: 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a  nto a string .**
e9b0: 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
e9c0: 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
e9d0: 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
e9e0: 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
e9f0: 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
ea00: 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
ea10: 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
ea20: 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20   string.  Or if 
ea30: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
ea40: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
ea50: 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
ea60: 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
ea70: 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
ea80: 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
ea90: 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65   single.** quote
eaa0: 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
eab0: 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45  he %Q option. {E
eac0: 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  ND}  So, for exa
ead0: 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
eae0: 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
eaf0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
eb00: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
eb10: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
eb20: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
eb30: 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
eb40: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
eb50: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
eb60: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
eb70: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
eb80: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
eb90: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
eba0: 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
ebb0: 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
ebc0: 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
ebd0: 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
ebe0: 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
ebf0: 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
ec00: 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
ec10: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
ec20: 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
ec30: 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
ec40: 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
ec50: 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
ec60: 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
ec70: 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
ec80: 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
ec90: 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
eca0: 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
ecb0: 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
ecc0: 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
ecd0: 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
ece0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
ecf0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d  :.**.** {F17403}
ed00: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
ed10: 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
ed20: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
ed30: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
ed40: 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
ed50: 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
ed60: 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
ed70: 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
ed80: 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
ed90: 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
eda0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
edb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
edc0: 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
edd0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
ede0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
edf0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
ee00: 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34  ils..**.** {F174
ee10: 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
ee20: 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
ee30: 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
ee40: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
ee50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
ee60: 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
ee70: 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
ee80: 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
ee90: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
eea0: 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
eeb0: 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
eec0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
eed0: 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
eee0: 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37  o..**.** {F17407
eef0: 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
ef00: 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
ef10: 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
ef20: 72 69 74 65 73 20 73 6c 6f 74 73 20 6f 66 0a 2a  rites slots of.*
ef30: 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20  *           its 
ef40: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74  output buffer (t
ef50: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
ef60: 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65  ter) outside the
ef70: 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20   range.**       
ef80: 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68      of 0 through
ef90: 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73   N-1 (where N is
efa0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
efb0: 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20  eter).**        
efc0: 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66     regardless of
efd0: 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
efe0: 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  he string.**    
eff0: 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64         requested
f000: 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73   by the format s
f010: 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a  pecification..**
f020: 20 20 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c     .*/.char *sql
f030: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
f040: 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
f050: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
f060: 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
f070: 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
f080: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
f090: 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
f0a0: 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
f0b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f0c0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
f0d0: 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46  ion Subsystem {F
f0e0: 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17300}.**.** The
f0f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73   SQLite core  us
f100: 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
f110: 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
f120: 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
f130: 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
f140: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
f150: 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
f160: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
f170: 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
f180: 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
f190: 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
f1a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
f1b0: 2e 20 20 54 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  .  The.** window
f1c0: 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
f1d0: 65 20 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 72 65  e malloc and fre
f1e0: 65 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  e for some opera
f1f0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
f200: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f210: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
f220: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f230: 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
f240: 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
f250: 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
f260: 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
f270: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20  arameter..** If 
f280: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f290: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
f2a0: 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
f2b0: 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
f2c0: 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
f2d0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74  L pointer.  If t
f2e0: 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
f2f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
f300: 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
f310: 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
f320: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
f330: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
f340: 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
f350: 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   Calling sqlite3
f360: 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
f370: 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
f380: 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
f390: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f3a0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
f3b0: 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
f3c0: 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
f3d0: 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
f3e0: 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20  be reused.  The 
f3f0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
f400: 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
f410: 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
f420: 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
f430: 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
f440: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
f450: 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
f460: 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
f470: 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
f480: 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
f490: 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
f4a0: 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
f4b0: 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
f4c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
f4d0: 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
f4e0: 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
f4f0: 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
f500: 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
f510: 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
f520: 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
f530: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
f540: 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
f550: 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
f560: 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
f570: 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
f580: 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
f590: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
f5a0: 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
f5b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
f5c0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
f5d0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a  sqlite3_free()..
f5e0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f5f0: 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
f600: 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
f610: 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
f620: 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
f630: 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
f640: 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
f650: 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
f660: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
f670: 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
f680: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
f690: 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
f6a0: 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
f6b0: 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
f6c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
f6d0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
f6e0: 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
f6f0: 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
f700: 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
f710: 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
f720: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f730: 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
f740: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
f750: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
f760: 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74  alloc()..** If t
f770: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
f780: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
f790: 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
f7a0: 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
f7b0: 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
f7c0: 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
f7d0: 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
f7e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
f7f0: 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
f800: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
f810: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
f820: 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c 69  alloc()..** Sqli
f830: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
f840: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
f850: 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
f860: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
f870: 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
f880: 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
f890: 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
f8a0: 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
f8b0: 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68  e..** If M is th
f8c0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
f8d0: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
f8e0: 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
f8f0: 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
f900: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
f910: 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
f920: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
f930: 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
f940: 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
f950: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
f960: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
f970: 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   is freed..** If
f980: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
f990: 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
f9a0: 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
f9b0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
f9c0: 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
f9d0: 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74  * The memory ret
f9e0: 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
f9f0: 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
fa00: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
fa10: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
fa20: 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
fa30: 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
fa40: 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ary. {END}.**.**
fa50: 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70   The default imp
fa60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
fa70: 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  f the memory all
fa80: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
fa90: 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f  m uses the mallo
faa0: 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a  c(), realloc().*
fab0: 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f  * and free() pro
fac0: 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61  vided by the sta
fad0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
fae0: 20 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65   {F17382} Howeve
faf0: 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65  r, if .** SQLite
fb00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fb10: 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  h the following 
fb20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
fb30: 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  acro.**.** <bloc
fb40: 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d  kquote> SQLITE_M
fb50: 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e  EMORY_SIZE=<i>NN
fb60: 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f  N</i> </blockquo
fb70: 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  te>.**.** where 
fb80: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e  <i>NNN</i> is an
fb90: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53   integer, then S
fba0: 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
fbb0: 74 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f  tatic.** array o
fbc0: 66 20 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e  f at least <i>NN
fbd0: 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
fbe0: 69 7a 65 20 61 6e 64 20 75 73 65 20 74 68 61 74  ize and use that
fbf0: 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c   array.** for al
fc00: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
fc10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fc20: 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
fc30: 20 41 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d   Additional.** m
fc40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
fc50: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
fc60: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
fc70: 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
fc80: 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
fc90: 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
fca0: 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
fcb0: 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
fcc0: 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
fcd0: 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
fce0: 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
fcf0: 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
fd00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fd10: 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
fd20: 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
fd30: 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
fd40: 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
fd50: 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
fd60: 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
fd70: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
fd80: 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a  an be.** used..*
fd90: 2a 0a 2a 2a 20 54 68 65 20 77 69 6e 64 6f 77 73  *.** The windows
fda0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
fdb0: 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
fdc0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
fdd0: 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
fde0: 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
fdf0: 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
fe00: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
fe10: 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
fe20: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
fe30: 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
fe40: 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
fe50: 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
fe60: 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a  ticular windows.
fe70: 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
fe80: 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
fe90: 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
fea0: 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
feb0: 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
fec0: 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
fed0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
fee0: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
fef0: 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
ff00: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
ff10: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
ff20: 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54  *.** {F17303}  T
ff30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
ff40: 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
ff50: 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20   returns either 
ff60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a  a pointer to .**
ff70: 20 20 20 20 20 20 20 20 20 20 20 6e 65 77 6c 79             newly
ff80: 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f   checked-out blo
ff90: 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ck of at least N
ffa0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
ffb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
ffc0: 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
ffd0: 67 6e 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20 20  gned, .**       
ffe0: 20 20 20 20 6f 72 20 69 74 20 72 65 74 75 72 6e      or it return
fff0: 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20  s NULL if it is 
10000 75 6e 61 62 6c 65 20 74 6f 20 66 75 6c 66 69 6c  unable to fulfil
10010 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a  l the request..*
10020 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54  *.** {F17304}  T
10030 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
10040 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
10050 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
10060 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20  pointer if.**   
10070 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73          N is les
10080 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
10090 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  to zero..**.** {
100a0 46 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71  F17305}  The [sq
100b0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69  lite3_free(P)] i
100c0 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65  nterface release
100d0 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75  s memory previou
100e0 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
100f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
10100 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10110 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
10120 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
10130 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74         making it
10140 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72   available for r
10150 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  euse..**.** {F17
10160 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  306}  A call to 
10170 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55  [sqlite3_free(NU
10180 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65  LL)] is a harmle
10190 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
101a0 7b 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c  {F17310}  A call
101b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   to [sqlite3_rea
101c0 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71  lloc(0,N)] is eq
101d0 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61  uivalent to a ca
101e0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ll.**           
101f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
10200 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  oc(N)]..**.** {F
10210 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74  17312}  A call t
10220 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
10230 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69  oc(P,0)] is equi
10240 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
10250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
10260 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
10270 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  )]..**.** {F1731
10280 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  5}  The SQLite c
10290 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65  ore uses [sqlite
102a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
102b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
102c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  ,.**           a
102d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  nd [sqlite3_free
102e0 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ()] for all of i
102f0 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ts memory alloca
10300 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
10310 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69        deallocati
10320 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  on needs..**.** 
10330 7b 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73  {F17318}  The [s
10340 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
10350 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
10360 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
10370 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
10380 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20       to a block 
10390 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d  of checked-out m
103a0 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
103b0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
103c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
103d0 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
103e0 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c  igned, or a NULL
103f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
10400 7b 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b  {F17321}  When [
10410 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10420 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
10430 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
10440 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
10450 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74          copies t
10460 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73  he first K bytes
10470 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d   of content from
10480 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c   P into the newl
10490 79 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20  y allocated.**  
104a0 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4b           where K
104b0 20 69 73 20 74 68 65 20 6c 65 73 73 6f 72 20 6f   is the lessor o
104c0 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65  f N and the size
104d0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 50   of the buffer P
104e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d  ..**.** {F17322}
104f0 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
10500 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
10510 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
10520 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
10530 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
10540 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66  releases the buf
10550 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fer P..**.** {F1
10560 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7323}  When [sql
10570 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
10580 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  )] returns NULL,
10590 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73   the buffer P is
105a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
105b0 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65  t modified or re
105c0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49  leased..**.** LI
105d0 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
105e0 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20 70   {U17350}  The p
105f0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
10600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
10610 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
10620 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
10630 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62            must b
10640 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
10650 20 65 6c 73 65 20 61 20 70 6f 69 6e 74 65 72 20   else a pointer 
10660 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
10670 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
10680 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66     invocation of
10690 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
106a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
106b0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
106c0 68 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  has.**          
106d0 20 6e 6f 74 20 62 65 65 6e 20 72 65 6c 65 61 73   not been releas
106e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35  ed..**.** {U1735
106f0 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
10700 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
10710 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
10720 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20  art of .**      
10730 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20       a block of 
10740 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
10750 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
10760 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
10770 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72       [sqlite3_fr
10780 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
10790 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  3_realloc()]..**
107a0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
107b0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
107c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
107d0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
107e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
107f0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
10800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
10810 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
10820 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 37 30  atistics {F17370
10830 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  }.**.** SQLite p
10840 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
10850 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
10860 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
10870 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
10880 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
10890 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
108a0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
108b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
108c0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
108d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
108e0 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
108f0 68 69 6e 20 74 68 65 20 53 51 4c 69 74 65 2e 0a  hin the SQLite..
10900 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10910 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d  :.**.** {F17371}
10920 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
10930 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
10940 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
10950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
10960 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
10970 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
10980 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a 2a   outstanding .**
10990 20 20 20 20 20 20 20 20 20 20 28 6d 61 6c 6c 6f            (mallo
109a0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
109b0 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  d)..**.** {F1737
109c0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
109d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
109e0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
109f0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
10a00 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
10a10 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
10a20 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a 2a  mory_used()] .**
10a30 20 20 20 20 20 20 20 20 20 20 73 69 6e 63 65 20            since 
10a40 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61  the highwater ma
10a50 72 6b 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  rk was last rese
10a60 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34  t..**.** {F17374
10a70 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74  } The values ret
10a80 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
10a90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
10aa0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
10ab0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10ac0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
10ad0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
10ae0 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ad.**          a
10af0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
10b00 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
10b10 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
10b20 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  _malloc()],.**  
10b30 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20          but not 
10b40 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
10b50 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
10b60 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
10b70 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ary.**          
10b80 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
10b90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10ba0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a   may call..** .*
10bb0 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65 20 6d  * {F17375} The m
10bc0 65 6d 6f 72 79 20 68 69 67 68 77 61 74 65 72 20  emory highwater 
10bd0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
10be0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
10bf0 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ue of.**        
10c00 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
10c10 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
10c20 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
10c30 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
10c40 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
10c50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
10c60 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65  )] is true.  The
10c70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
10c80 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
10c90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
10ca0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
10cb0 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61  the highwater ma
10cc0 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  rk.**          p
10cd0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
10ce0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
10cf0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
10d00 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
10d10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
10d20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
10d30 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
10d40 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
10d50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
10d60 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
10d70 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  n Callbacks {F12
10d80 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500}.**.** This 
10d90 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
10da0 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
10db0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
10dc0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 64 61 74  articular.** dat
10dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10de0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
10df0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10e00 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
10e10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
10e20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
10e30 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
10e40 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
10e50 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
10e60 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
10e70 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
10e80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
10e90 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
10ea0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
10eb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
10ec0 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75  2()].  At variou
10ed0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
10ee0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
10ef0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
10f00 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
10f10 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
10f20 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
10f30 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
10f40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
10f50 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
10f60 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
10f70 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
10f80 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
10f90 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
10fa0 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ** return SQLITE
10fb0 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  _OK to allow the
10fc0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
10fd0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
10fe0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
10ff0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
11000 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
11010 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
11020 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
11030 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
11040 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
11050 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
11060 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
11070 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
11080 20 61 6e 20 65 72 72 6f 72 2e 20 20 20 49 66 20   an error.   If 
11090 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
110a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
110b0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
110c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
110d0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
110e0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
110f0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b  _DENY].** then [
11100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
11110 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
11120 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
11130 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
11140 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
11150 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
11160 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
11170 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
11180 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
11190 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
111a0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
111b0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
111c0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
111d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
111e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
111f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
11200 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
11210 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
11220 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
11230 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
11240 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
11250 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
11260 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
11270 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
11280 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
11290 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
112a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
112b0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
112c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
112d0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
112e0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
112f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
11300 73 74 72 75 63 74 65 64 20 74 6f 20 69 6e 73 65  structed to inse
11310 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  rt a NULL value 
11320 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
11330 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
11340 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
11350 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
11360 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
11370 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
11380 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
11390 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
113a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
113b0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
113c0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
113d0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
113e0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
113f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
11400 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
11410 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
11420 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
11430 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  f.** the third p
11440 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
11450 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
11460 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
11470 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ce..** The secon
11480 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
11490 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
114a0 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53  n integer .** [S
114b0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
114c0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
114d0 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
114e0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
114f0 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  * to be authoriz
11500 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68  ed. The third th
11510 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70  rough sixth.** p
11520 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
11530 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
11540 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
11550 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
11560 69 6e 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  in .** additiona
11570 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
11580 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
11590 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
115a0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
115b0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72   is used when pr
115c0 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74  eparing SQL stat
115d0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
115e0 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72  ntrusted.** sour
115f0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
11600 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
11610 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79  ments do not try
11620 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a   to access data.
11630 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65  ** that they are
11640 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
11650 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
11660 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a  y do not try to.
11670 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  ** execute malic
11680 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
11690 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
116a0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
116b0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
116c0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
116d0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
116e0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
116f0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
11700 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
11710 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
11720 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
11730 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
11740 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
11750 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
11760 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
11770 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
11780 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
11790 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
117a0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
117b0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
117c0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
117d0 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61  ing prepared tha
117e0 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  t disallows ever
117f0 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74  ything.** except
11800 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
11810 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  ts.  .**.** Only
11820 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
11830 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
11840 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
11850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
11860 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
11870 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
11880 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
11890 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
118a0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
118b0 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
118c0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
118d0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
118e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
118f0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
11900 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11910 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
11920 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
11930 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
11940 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
11950 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72   .** [sqlite3_pr
11960 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
11970 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
11980 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
11990 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
119a0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
119b0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
119c0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
119d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
119e0 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54  **.** {F12501} T
119f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
11a00 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e  authorizer(D,...
11a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
11a20 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20  isters a.**     
11a30 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
11a40 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61  callback with da
11a50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11a60 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  n D..**.** {F125
11a70 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a  02} The authoriz
11a80 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
11a90 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
11aa0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
11ab0 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63           being c
11ac0 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46  ompiled.**.** {F
11ad0 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
11ae0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
11af0 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
11b00 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
11b10 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
11b20 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
11b30 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
11b40 49 54 45 5f 44 45 4e 59 5d 20 74 68 65 6e 0a 2a  ITE_DENY] then.*
11b50 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
11b60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
11b70 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
11b80 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ent call that ca
11b90 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  used.**         
11ba0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
11bb0 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
11bc0 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20  shall fail with 
11bd0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
11be0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
11bf0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
11c00 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
11c10 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
11c20 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20 74   {F12504} When t
11c30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11c40 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
11c50 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20  SQLITE_OK], the 
11c60 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  operation.**    
11c70 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20        described 
11c80 69 73 20 63 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c  is coded normall
11c90 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35  y..**.** {F12505
11ca0 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f  } When the autho
11cb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
11cc0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
11cd0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20  ENY], the.**    
11ce0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
11cf0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
11d00 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
11d10 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a  that caused the.
11d20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
11d30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
11d40 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
11d50 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  l.**          wi
11d60 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52  th an [SQLITE_ER
11d70 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
11d80 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
11d90 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
11da0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
11db0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
11dc0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36  d..**.** {F12506
11dd0 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
11de0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
11df0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
11e00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
11e10 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
11e20 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ck) is [SQLITE_R
11e30 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74  EAD] and the aut
11e40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
11e60 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
11e70 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70 72  ORE] then the pr
11e80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11e90 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
11ea0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
11eb0 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c  nsert a NULL val
11ec0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
11ed0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
11ee0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
11ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e  **          been
11f00 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
11f10 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
11f20 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  turned..**.** {F
11f30 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61 75  12507} If the au
11f40 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
11f50 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
11f60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
11f70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
11f80 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74  allback) is anyt
11f90 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
11fa0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74  [SQLITE_READ], t
11fb0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
11fc0 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c  a return of [SQL
11fd0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20  ITE_IGNORE] has 
11fe0 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20  the same effect 
11ff0 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  as [SQLITE_DENY]
12000 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30  . .**.** {F12510
12010 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
12020 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
12030 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12040 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
12050 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68            the th
12060 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
12070 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
12080 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
12090 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
120a0 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73 65   {F12511} The se
120b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
120c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
120d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a  s an integer .**
120e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
120f0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
12100 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
12110 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
12120 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  lar action.**   
12130 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74         to be aut
12140 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
12150 46 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72  F12512} The thir
12160 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
12170 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
12180 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a  e callback are.*
12190 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
121a0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
121b0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
121c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
121d0 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
121e0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
121f0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
12200 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30  d..**.** {F12520
12210 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
12220 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
12230 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69  orizer()] overri
12240 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  des the.**      
12250 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73      any previous
12260 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74  ly installed aut
12270 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  horizer..**.** {
12280 46 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61  F12521} A NULL a
12290 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
122a0 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
122b0 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
122c0 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e    callback is in
122d0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
122e0 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2522} The defaul
122f0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  t authorizer is 
12300 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
12310 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
12320 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
12330 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
12340 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
12350 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
12360 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
12370 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
12380 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
12390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
123a0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
123b0 75 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39  urn Codes {F1259
123c0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0}.**.** The [sq
123d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
123e0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
123f0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
12400 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
12410 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
12420 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
12430 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
12440 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
12450 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
12460 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
12470 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
12480 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
12490 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
124a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
124b0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
124c0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
124d0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
124e0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
124f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
12500 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
12510 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
12520 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
12530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12540 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
12550 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
12560 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
12570 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
12580 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
12590 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
125a0 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35  tion Codes {F125
125b0 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  50}.**.** The [s
125c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
125d0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
125e0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
125f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
12600 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
12610 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
12620 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  r certain SQL st
12630 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
12640 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
12650 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
12660 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
12670 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
12680 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
12690 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
126a0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
126b0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
126c0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
126d0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
126e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
126f0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
12700 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
12710 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
12720 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
12730 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
12740 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75   is to be .** au
12750 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
12760 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
12770 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
12780 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
12790 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
127a0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
127b0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
127c0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
127d0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
127e0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
127f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
12800 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
12810 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
12820 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
12830 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
12840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
12850 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a  main", "temp", .
12860 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
12870 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
12880 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
12890 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
128a0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
128b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
128c0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
128d0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
128e0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
128f0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
12900 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
12910 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
12920 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
12930 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76  from .** top-lev
12940 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a  el SQL code..**.
12950 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
12960 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20 54 68  *.** {F12551} Th
12970 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
12980 65 72 20 74 6f 20 61 6e 20 0a 2a 2a 20 20 20 20  er to an .**    
12990 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
129a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
129b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
129c0 61 63 6b 20 69 73 20 61 6c 77 61 79 73 20 61 6e  ack is always an
129d0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
129e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
129f0 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
12a00 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
12a10 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a  ies what action.
12a20 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62  **          is b
12a30 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
12a40 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 7d 20  .**.** {F12552} 
12a50 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
12a60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
12a70 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  e .**          [
12a80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
12a90 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
12aa0 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  zation callback 
12ab0 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20  function].**    
12ac0 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61        will be pa
12ad0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
12ae0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
12af0 69 63 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ich .**         
12b00 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
12b10 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
12b20 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
12b30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12b40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d  ..**.** {F12553}
12b50 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
12b60 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
12b70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
12b80 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
12b90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
12ba0 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65  ack] is the name
12bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
12bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65 78  the database (ex
12bd0 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22  ample: "main", "
12be0 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20  temp", etc.) if 
12bf0 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a  applicable..**.*
12c00 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20 36  * {F12554} The 6
12c10 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
12c20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12c30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12c40 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
12c50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
12c60 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
12c70 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e         of the in
12c80 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
12c90 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
12ca0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
12cc0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
12cd0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
12ce0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
12cf0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20  s directly from 
12d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70  .**          top
12d10 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
12d20 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
12d30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d50 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
12d60 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
12d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12d80 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
12d90 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
12da0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
12db0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
12dc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12dd0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
12de0 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
12df0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
12e00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
12e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12e20 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
12e30 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
12e40 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
12e50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
12e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12e70 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
12e80 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
12e90 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
12ea0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
12eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
12ec0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
12ed0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
12ee0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
12ef0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
12f00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
12f10 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
12f20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
12f30 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
12f40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
12f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
12f60 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
12f70 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
12f80 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
12f90 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
12fa0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
12fb0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
12fc0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
12fd0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
12fe0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
12ff0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
13000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
13010 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
13020 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
13030 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13040 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
13050 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
13060 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
13070 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
13080 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13090 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
130a0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
130b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
130c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
130d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
130e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
130f0 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
13100 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
13110 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
13120 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13130 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
13140 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
13150 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13160 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13180 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
13190 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
131a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
131b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
131c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
131d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
131e0 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
131f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
13200 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13220 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
13230 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
13240 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
13250 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13270 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
13280 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
13290 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
132a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
132b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
132c0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
132d0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
132e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
132f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13310 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
13320 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
13330 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
13340 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
13350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
13360 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
13370 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
13380 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
13390 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
133a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
133b0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
133c0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
133d0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
133e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
133f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
13400 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
13410 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    22   /* NULL  
13420 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
13430 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13440 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
13450 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
13460 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
13470 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
13480 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
13490 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
134a0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
134b0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
134c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
134d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
134e0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
134f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
13500 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
13510 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
13520 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13530 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
13540 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
13550 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
13560 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
13570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13580 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
13590 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
135a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
135b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
135c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
135d0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
135e0 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
135f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
13600 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13620 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
13630 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
13640 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13650 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
13660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13670 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
13680 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
13690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
136a0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
136b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
136c0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
136d0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
136e0 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
136f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13710 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
13720 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
13730 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
13740 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
13750 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
13760 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
13770 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a  ns {F12280}.**.*
13780 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
13790 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
137a0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
137b0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
137c0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
137d0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
137e0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
137f0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
13800 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
13810 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
13820 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
13830 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
13840 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
13850 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
13860 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
13870 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
13880 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
13890 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  The callback ret
138a0 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e  urns a UTF-8 ren
138b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51  dering of the SQ
138c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
138d0 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65  .** as the state
138e0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
138f0 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64  s executing.  Ad
13900 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63  ditional callbac
13910 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ks occur.** as e
13920 61 63 68 20 74 72 69 67 67 65 72 73 75 62 70 72  ach triggersubpr
13930 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
13940 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
13950 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
13960 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
13970 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
13980 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
13990 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a   trigger..** .**
139a0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
139b0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
139c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
139d0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
139e0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
139f0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
13a00 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c  hes.  The profil
13a10 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
13a20 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
13a30 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
13a40 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
13a50 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
13a60 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
13a70 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
13a80 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
13a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13aa0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49  e3_profile() API
13ab0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
13ac0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
13ad0 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20  ental and.** is 
13ae0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
13af0 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20  e or removal in 
13b00 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
13b10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67  ..**.** The trig
13b20 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66 65  ger reporting fe
13b30 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 72 61  ature of the tra
13b40 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  ce callback is c
13b50 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 70  onsidered.** exp
13b60 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
13b70 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
13b80 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e  ge or removal in
13b90 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
13ba0 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72 73  ..** Future vers
13bb0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
13bc0 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e 65  ight also add ne
13bd0 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  w trace callback
13be0 20 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73   .** invocations
13bf0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
13c00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  TS:.**.** {F1228
13c10 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
13c20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
13c30 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
13c40 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20  trace()] is.**  
13c50 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
13c60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
13c70 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  t first begins t
13c80 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a  o execute and.**
13c90 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
13ca0 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62  er a trigger sub
13cb0 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65  program first be
13cc0 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  gins to run..**.
13cd0 2a 2a 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68  ** {F12282} Each
13ce0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
13cf0 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72  3_trace()] overr
13d00 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ides the previou
13d10 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
13d20 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65  registered trace
13d30 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
13d40 20 7b 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c   {F12283} A NULL
13d50 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
13d60 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67  disables tracing
13d70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d  ..**.** {F12284}
13d80 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13d90 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
13da0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
13db0 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
13dc0 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77     the pointer w
13dd0 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64  hich was the 3rd
13de0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
13df0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a  lite3_trace()]..
13e00 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54  **.** {F12285} T
13e10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13e20 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
13e30 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
13e40 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
13e50 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73  erminated UTF8 s
13e60 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
13e70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65   the original te
13e80 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  xt.**          o
13e90 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
13ea0 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61  ent as it was pa
13eb0 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74  ssed into [sqlit
13ec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
13ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
13ee0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20  the equivalent, 
13ef0 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
13f00 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  t indicating the
13f10 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20   beginning.**   
13f20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67         of a trig
13f30 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a  ger subprogram..
13f40 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54  **.** {F12287} T
13f50 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
13f60 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
13f70 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  by [sqlite3_prof
13f80 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ile()] is invoke
13f90 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  d.**          as
13fa0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
13fb0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
13fc0 0a 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 68 65  .** {F12288} The
13fd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13fe0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
13ff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
14000 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
14010 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65    the 3rd parame
14020 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
14030 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  profile()]..**.*
14040 2a 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20 73  * {F12289} The s
14050 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14060 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
14070 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
14080 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
14090 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
140a0 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
140b0 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
140c0 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20   text of.**     
140d0 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61       the SQL sta
140e0 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
140f0 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73   processed by [s
14100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14110 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
14120 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
14130 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39  nt..**.** {F1229
14140 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72  0} The third par
14150 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
14160 6f 66 69 6c 65 20 20 63 61 6c 6c 62 61 63 6b 20  ofile  callback 
14170 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a  is an estimate.*
14180 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
14190 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
141a0 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d  seconds of wall-
141b0 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69  clock time requi
141c0 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  red to.**       
141d0 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73     run the SQL s
141e0 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74  tatement from st
141f0 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a  art to finish..*
14200 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
14210 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
14220 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
14230 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
14240 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
14250 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
14260 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
14270 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
14280 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
14290 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
142a0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
142b0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
142c0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
142d0 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a  s {F12910}.**.**
142e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
142f0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
14300 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
14310 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
14320 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
14330 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
14340 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
14350 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
14360 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
14370 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
14380 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
14390 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
143a0 62 6c 65 28 29 5d 2e 20 20 20 41 6e 20 65 78 61  ble()].   An exa
143b0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
143c0 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  s .** interface 
143d0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
143e0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
143f0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
14400 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67  *.** If the prog
14410 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
14420 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
14430 74 68 65 20 6f 70 65 72 74 69 6f 6e 20 69 73 0a  the opertion is.
14440 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
14450 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
14460 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
14470 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
14480 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
14490 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e   GUI dialog box.
144a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
144b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31  S:.**.** {F12911
144c0 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
144d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
144e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
144f0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
14500 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
14510 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
14520 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
14530 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
14540 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
14550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14560 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d  ..**.** {F12912}
14570 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
14580 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
14590 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79  d once for every
145a0 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20   N virtual.**   
145b0 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f         machine o
145c0 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20  pcodes, where N 
145d0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
145e0 67 75 6d 65 6e 74 20 74 6f 20 0a 2a 2a 20 20 20  gument to .**   
145f0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
14600 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14610 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61  dler()] call tha
14620 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  t registered.** 
14630 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
14640 6c 62 61 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68  lback.  <todo>Wh
14650 61 74 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  at if N is less 
14660 74 68 61 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a  than 1?</todo>.*
14670 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68  *.** {F12913} Th
14680 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14690 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
146a0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
146b0 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
146c0 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73    argument to [s
146d0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
146e0 68 61 6e 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a  handler()]..**.*
146f0 2a 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66  * {F12914} The f
14700 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 5b  ourth argument [
14710 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
14720 5f 68 61 6e 64 6c 65 72 28 29 5d 20 69 73 20 61  _handler()] is a
14730 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 76 6f 69  .***         voi
14740 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
14750 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
14760 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
14770 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65        function e
14780 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
14790 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
147a0 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c  12915} If a call
147b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
147c0 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20  p()] results in 
147d0 66 65 77 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  fewer than.**   
147e0 20 20 20 20 20 20 20 4e 20 6f 70 63 6f 64 65 73         N opcodes
147f0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
14800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14810 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  n the progress c
14820 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72  allback is never
14830 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a   invoked. {END}.
14840 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20  ** .** {F12916} 
14850 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73  Every call to [s
14860 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
14870 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20  handler()].**   
14880 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65         overwrite
14890 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  s any previously
148a0 20 72 65 67 69 73 74 65 72 65 20 70 72 6f 67 72   registere progr
148b0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  ess handler..**.
148c0 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 20 74  ** {F12917} If t
148d0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
148e0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
148f0 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f  NULL then no pro
14900 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20  gress.**        
14910 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76    handler is inv
14920 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
14930 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67  918} If the prog
14940 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
14950 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f  turns a result o
14960 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65  ther than 0, the
14970 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
14980 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20  e behavior is a 
14990 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  if [sqlite3_inte
149a0 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65  rrupt()] had bee
149b0 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69  n called..*/.voi
149c0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
149d0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
149e0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
149f0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
14a00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14a10 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
14a20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
14a30 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a  ion {F12700}.**.
14a40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
14a50 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
14a60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
14a70 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20  hose name.** is 
14a80 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 69 6c  given by the fil
14a90 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 0a  ename argument..
14aa0 2a 2a 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  ** The filename 
14ab0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
14ac0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
14ad0 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  .** for [sqlite3
14ae0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
14af0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
14b00 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a   and as UTF-16.*
14b10 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
14b20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
14b30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
14b40 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  ]..** An [sqlite
14b50 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  3*] handle is us
14b60 75 61 6c 6c 79 20 72 65 74 75 72 6e 65 64 20 69  ually returned i
14b70 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a  n *ppDb, even.**
14b80 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
14b90 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
14ba0 78 63 65 70 74 69 6f 6e 20 69 73 20 69 66 20 53  xception is if S
14bb0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 0a  QLite is unable.
14bc0 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ** to allocate m
14bd0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
14be0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
14bf0 63 74 2c 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a  ct, a NULL will.
14c00 2a 2a 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ** be written in
14c10 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
14c20 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
14c30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
14c40 62 6a 65 63 74 2e 0a 2a 2a 20 49 66 20 74 68 65  bject..** If the
14c50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
14c60 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
14c70 74 65 64 29 0a 2a 2a 20 73 75 63 63 65 73 73 66  ted).** successf
14c80 75 6c 6c 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49  ully, then [SQLI
14c90 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
14ca0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
14cb0 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
14cc0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
14cd0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
14ce0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
14cf0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
14d00 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
14d10 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
14d20 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
14d30 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
14d40 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
14d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
14d60 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
14d70 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
14d80 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
14d90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
14da0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
14db0 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c  en_v2()] is call
14dc0 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
14dd0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
14de0 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b 73 71  yte order if [sq
14df0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
14e00 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
14e10 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
14e20 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
14e30 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
14e40 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
14e50 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
14e60 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  e [sqlite3*] han
14e70 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
14e80 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69 6e  leased by passin
14e90 67 20 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  g it.** to [sqli
14ea0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
14eb0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
14ec0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
14ed0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  * The [sqlite3_o
14ee0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
14ef0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b  ace works like [
14f00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
14f10 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
14f20 69 74 20 61 63 63 63 65 70 74 73 20 74 77 6f 20  it acccepts two 
14f30 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
14f40 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
14f50 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
14f60 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
14f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14f80 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
14f90 61 6d 65 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a  ameter can be.**
14fa0 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c   one of:.**.** <
14fb0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ol>.** <li>  [SQ
14fc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
14fd0 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  LY].** <li>  [SQ
14fe0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
14ff0 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  ITE].** <li>  [S
15000 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
15010 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
15020 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20  OPEN_CREATE].** 
15030 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ol>.**.** The 
15040 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e  first value open
15050 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72  s the database r
15060 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66  ead-only. .** If
15070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
15080 65 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  es not previousl
15090 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
150a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
150b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74  * The second opt
150c0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65  ion opens.** the
150d0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
150e0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
150f0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
15100 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69  r reading only i
15110 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  f.** if the file
15120 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
15130 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72 20  ted.  In either 
15140 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
15150 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61 64  e.** must alread
15160 79 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72  y exist or an er
15170 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
15180 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69    The third opti
15190 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20  on.** opens the 
151a0 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
151b0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
151c0 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 20   and creates it 
151d0 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
151e0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
151f0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70  .** The third op
15200 74 69 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f  tions is behavio
15210 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
15220 20 75 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74   used for [sqlit
15230 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e  e3_open()].** an
15240 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
15250 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  6()]..**.** If t
15260 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
15270 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
15280 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e  an private.** in
15290 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
152a0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
152b0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
152c0 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a   This in-memory.
152d0 2a 2a 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ** database will
152e0 20 76 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65   vanish when the
152f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15300 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
15310 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
15320 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  on of SQLite mig
15330 68 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ht make use of a
15340 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
15350 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74  l filenames.** t
15360 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
15370 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
15380 2e 20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  .  It is recomme
15390 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68  nded that .** wh
153a0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
153b0 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f  lename really do
153c0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
153d0 20 22 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72   ":" that you pr
153e0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
153f0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
15400 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a  e like "./" to.*
15410 2a 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  * avoid ambiguit
15420 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
15430 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
15440 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
15450 6e 20 61 20 70 72 69 76 61 74 65 20 74 65 6d 70  n a private temp
15460 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
15470 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
15480 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73  e created.  This
15490 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
154a0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
154b0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
154c0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
154d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
154e0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
154f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
15500 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
15510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15520 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
15530 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15540 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
15550 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
15560 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a  rating system .*
15570 2a 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  * interface that
15580 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
15590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
155a0 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65  uld use.  If the
155b0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
155c0 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70  eter is a NULL p
155d0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
155e0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
155f0 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  _vfs].** object 
15600 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
15610 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77  b>Note to window
15620 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
15630 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
15640 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
15650 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
15660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15670 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
15680 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65  en_v2()] must be
15690 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
156a0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
156b0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
156c0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
156d0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
156e0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
156f0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
15700 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
15710 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
15720 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
15730 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
15740 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
15750 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  pen_v2()]..**.**
15760 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
15770 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20  ** {F12701} The 
15780 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15790 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
157a0 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
157b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
157c0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
157d0 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65  aces create a ne
157e0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
157f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15800 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
15810 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
15820 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
15830 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72  e given in their
15840 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15850 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d  ..**.** {F12702}
15860 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
15870 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
15880 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
15890 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b  *          for [
158a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
158b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
158c0 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55  n_v2()] and as U
158d0 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
158e0 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
158f0 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
15900 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
15910 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33  ]..**.** {F12703
15920 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
15930 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
15940 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
15950 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
15960 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ], .**          
15970 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15980 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20  _v2()] writes a 
15990 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77  pointer to a new
159a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
159b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
159c0 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a  n] into *ppDb..*
159d0 2a 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68  *.** {F12704} Th
159e0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
159f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15a00 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
15a10 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
15a20 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
15a30 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53  rfaces return [S
15a40 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73  QLITE_OK] upon s
15a50 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20  uccess,.**      
15a60 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70      or an approp
15a70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
15a80 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a  e] on failure..*
15a90 2a 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68  *.** {F12706} Th
15aa0 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65  e default text e
15ab0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65  ncoding for a ne
15ac0 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  w database creat
15ad0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
15ae0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
15af0 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
15b00 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c  3_open_v2()] wil
15b10 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  l be UTF-8..**.*
15b20 2a 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64  * {F12707} The d
15b30 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f  efault text enco
15b40 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64  ding for a new d
15b50 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20  atabase created 
15b60 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
15b70 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31    [sqlite3_open1
15b80 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46  6()] will be UTF
15b90 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  -16..**.** {F127
15ba0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
15bb0 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65  _open(F,D)] inte
15bc0 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
15bd0 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
15be0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
15bf0 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68  _v2(F,D,G,0)] wh
15c00 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65  ere the G parame
15c10 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
15c20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f     [SQLITE_OPEN_
15c30 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49  READWRITE]|[SQLI
15c40 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
15c50 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20  .**.** {F12711} 
15c60 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
15c70 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
15c80 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
15c90 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
15ca0 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
15cb0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
15cc0 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20  _READONLY] then 
15cd0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
15ce0 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
15cf0 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f     for reading o
15d00 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  nly..**.** {F127
15d10 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  12} If the G par
15d20 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15d30 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
15d40 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
15d50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
15d60 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
15d70 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
15d80 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
15d90 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
15da0 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20          reading 
15db0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
15dc0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20  ossible, or for 
15dd0 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20  reading only if 
15de0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
15df0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
15e00 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
15e10 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
15e20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20  .**.** {F12713} 
15e30 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
15e40 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
15e50 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen(v2(F,D,G,V)]
15e60 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20   omits the.**   
15e70 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
15e80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
15e90 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61  EATE] and the da
15ea0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
15eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76  **          prev
15ec0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e  iously exist, an
15ed0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
15ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ed..**.** {F1271
15ef0 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  4} If the G para
15f00 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
15f10 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c  3_open(v2(F,D,G,
15f20 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
15f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
15f40 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
15f50 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
15f60 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
15f70 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  s not.**        
15f80 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69    previously exi
15f90 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65  st, then an atte
15fa0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63  mpt is made to c
15fb0 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20  reate and.**    
15fc0 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65        initialize
15fd0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a   the database..*
15fe0 2a 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66  *.** {F12717} If
15ff0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
16000 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
16010 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
16020 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
16030 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
16040 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16050 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  )] is ":memory:"
16060 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74  , then an privat
16070 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
16080 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d  phemeral, in-mem
16090 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20  ory database is 
160a0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
160b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20  connection..**  
160c0 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73          <todo>Is
160d0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
160e0 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ATE|SQLITE_OPEN_
160f0 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72  READWRITE requir
16100 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
16110 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  n sqlite3_open_v
16120 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  2()?</todo>.**.*
16130 2a 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68  * {F12719} If th
16140 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
16150 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
16160 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 65  hen a private, e
16170 70 68 65 72 6d 65 72 61 6c 0a 2a 2a 20 20 20 20  phermeral.**    
16180 20 20 20 20 20 20 6f 6e 2d 64 69 73 6b 20 64 61        on-disk da
16190 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
161a0 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20  reated..**      
161b0 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
161c0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
161d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
161e0 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
161f0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
16200 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
16210 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
16220 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61  12721} The [data
16230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16240 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a 2a 20   created by .** 
16250 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
16260 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
16270 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74 68 65  V)] will use the
16280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16290 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
162a0 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
162b0 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
162c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
162d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
162e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
162f0 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c 4c 20   is V is a NULL 
16300 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  pointer..*/.int 
16310 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
16320 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
16330 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
16340 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
16350 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
16360 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
16370 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
16380 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
16390 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
163a0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
163b0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
163c0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
163d0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
163e0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
163f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
16400 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
16410 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
16420 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
16430 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
16440 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
16450 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
16460 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
16470 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
16480 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
16490 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
164a0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
164b0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
164c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
164d0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
164e0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
164f0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
16500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16510 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
16520 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31 32 38  d Messages {F128
16530 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
16540 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
16550 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16560 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
16570 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
16580 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53  sult code] or [S
16590 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
165a0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
165b0 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20  lt code].** for 
165c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
165d0 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
165e0 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
165f0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71  ated.** with [sq
16600 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64  lite3] handle 'd
16610 62 27 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  b'. If a prior A
16620 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62  PI call failed b
16630 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  ut the.** most r
16640 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
16650 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
16660 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
16670 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16680 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  ).** is undefine
16690 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
166a0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
166b0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
166c0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
166d0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
166e0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
166f0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
16700 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f 72  s either UTF8 or
16710 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69 76   UTF16 respectiv
16720 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74  ely..** Memory t
16730 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
16740 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
16750 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
16760 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
16770 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
16780 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
16790 20 77 69 74 68 20 66 72 65 65 69 6e 67 20 74 68   with freeing th
167a0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
167b0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
167c0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
167d0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
167e0 65 61 6c 6c 6f 63 61 74 65 64 20 62 0a 2a 2a 20  eallocated b.** 
167f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
16800 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
16810 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
16820 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
16830 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
16840 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12801} The [sqli
16850 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20  te3_errcode(D)] 
16860 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16870 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
16880 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
16890 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
168a0 64 65 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  de] or.**       
168b0 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52     [SQLITE_IOERR
168c0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
168d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
168e0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
168f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
16900 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
16910 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
16920 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
16930 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65  [sqlite3] handle
16940 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 38 30   D..**.** {U1280
16950 32 7d 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  2} If a prior AP
16960 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75  I call failed bu
16970 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
16980 74 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 20 20  t API call.**   
16990 20 20 20 20 20 20 20 73 75 63 63 65 65 64 65 64         succeeded
169a0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
169b0 75 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ue from [sqlite3
169c0 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
169d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
169e0 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
169f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
16a00 31 36 28 29 5d 20 61 72 65 20 75 6e 64 65 66 69  16()] are undefi
16a10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  ned..**.** {F128
16a20 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
16a30 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20  _errmsg(D)] and 
16a40 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
16a50 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  6(D)].**        
16a60 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
16a70 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
16a80 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64  uage text that d
16a90 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20  escribes.**     
16aa0 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69       the error i
16ab0 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63  n the mostly rec
16ac0 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
16ad0 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20  erface call,.** 
16ae0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64           encoded
16af0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
16b00 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
16b10 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  ively..**.** {U1
16b20 32 38 30 34 7d 20 54 68 65 20 73 74 72 69 6e 67  2804} The string
16b30 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
16b40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
16b50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
16b60 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
16b70 20 20 20 20 20 20 61 72 65 20 6f 6e 6c 79 20 76        are only v
16b80 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e  alid until the n
16b90 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ext SQLite inter
16ba0 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  face call..**.**
16bb0 20 7b 46 31 32 38 30 37 7d 20 43 61 6c 6c 73 20   {F12807} Calls 
16bc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
16bd0 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
16be0 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 0a  _errmsg()], and.
16bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16c00 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
16c10 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
16c20 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a 2a  ot affect the.**
16c30 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
16c40 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f  s of future invo
16c50 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  cations of these
16c60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
16c70 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20   {F12808} Calls 
16c80 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  to API routines 
16c90 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75  that do not retu
16ca0 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  rn an error code
16cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78  .**          (ex
16cc0 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f  ample: [sqlite3_
16cd0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64  data_count()]) d
16ce0 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  o not.**        
16cf0 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72    change the err
16d00 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61  or code or messa
16d10 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ge returned by.*
16d20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16d30 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
16d40 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
16d50 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
16d60 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a  errmsg16()]..**.
16d70 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65  ** {F12809} Inte
16d80 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20  rfaces that are 
16d90 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  not associated w
16da0 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a  ith a specific.*
16db0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
16dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16dd0 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20   (examples:.**  
16de0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
16df0 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b  _mprintf()] or [
16e00 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
16e10 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a  hared_cache()].*
16e20 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f  *          do no
16e30 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
16e40 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
16e50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16e60 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
16e70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
16e80 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
16e90 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
16ea0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
16eb0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
16ec0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
16ed0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
16ee0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
16ef0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
16f00 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
16f10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16f20 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
16f30 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a  Object {F13000}.
16f40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
16f50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
16f60 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
16f70 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
16f80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
16f90 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
16fa0 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74  nt single SQL st
16fb0 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a  atements.  This.
16fc0 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  ** object is var
16fd0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
16fe0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
16ff0 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20  ement" or a .** 
17000 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
17010 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
17020 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
17030 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  nt"..** .** The 
17040 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
17050 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
17060 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
17070 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
17080 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
17090 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
170a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
170b0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
170c0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
170d0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
170e0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
170f0 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69  t parameters usi
17100 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
17110 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
17120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69  sqlite3_bind_* i
17130 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c  nterfaces]..** <
17140 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
17150 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
17160 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
17170 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
17180 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
17190 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
171a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
171b0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
171c0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
171d0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
171e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
171f0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
17200 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
17210 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
17220 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
17230 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
17240 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
17250 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
17260 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
17270 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
17280 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
17290 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
172a0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
172b0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
172c0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
172d0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
172e0 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F13010}.**.** 
172f0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
17300 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
17310 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
17320 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
17330 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
17340 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
17350 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a  e routines. .**.
17360 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17370 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e  ument "db" is an
17380 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17390 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69  ction] .** obtai
173a0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
173b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
173c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
173d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a  te3_open_v2()].*
173e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
173f0 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65  en16()]. .** The
17400 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17410 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73   "zSql" is the s
17420 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
17430 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
17440 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
17450 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
17460 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
17470 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
17480 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
17490 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
174a0 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69  s UTF-8 and sqli
174b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
174c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
174d0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
174e0 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a  e UTF-16. {END}.
174f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
17500 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
17510 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f  ess.** than zero
17520 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
17530 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
17540 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
17550 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65  tor..** If nByte
17560 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
17570 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
17580 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
17590 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61  of .** bytes rea
175a0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
175b0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
175c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
175d0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
175e0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
175f0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
17600 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
17610 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20  er or .** until 
17620 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
17630 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
17640 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44 7d 0a  es first. {END}.
17650 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73  **.** *pzTail is
17660 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
17670 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
17680 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
17690 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51   the.** first SQ
176a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
176b0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
176c0 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c  ines only compil
176d0 65 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  es the first.** 
176e0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
176f0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
17700 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
17710 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a  o what remains.*
17720 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  * uncompiled..**
17730 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
17740 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
17750 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
17760 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
17770 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
17780 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
17790 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
177a0 20 4f 72 20 69 66 20 74 68 65 72 65 20 69 73 20   Or if there is 
177b0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
177c0 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 20  t may be.** set 
177d0 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65  to NULL.  If the
177e0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
177f0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
17800 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20  the input.** is 
17810 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67  and empty string
17820 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
17830 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
17840 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b  et to NULL..** {
17850 55 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c  U13018} The call
17860 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
17870 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
17880 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a   deleting the.**
17890 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
178a0 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67  atement.** using
178b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
178c0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
178d0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
178e0 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75   it..**.** On su
178f0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
17900 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
17910 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a   Otherwise an .*
17920 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
17930 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
17940 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
17950 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
17960 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
17970 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
17980 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
17990 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
179a0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
179b0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
179c0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
179d0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
179e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
179f0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
17a00 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
17a10 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
17a20 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
17a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
17a40 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
17a50 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
17a60 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
17a70 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
17a80 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69  of the .** origi
17a90 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b 45  nal SQL text. {E
17aa0 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 73 20  ND} This causes 
17ab0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
17ac0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
17ad0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
17ae0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
17af0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
17b00 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
17b10 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
17b20 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
17b30 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
17b40 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
17b50 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
17b60 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
17b70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
17b80 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
17b90 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
17ba0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
17bb0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
17bc0 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
17bd0 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
17be0 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
17bf0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
17c00 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
17c10 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
17c20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
17c30 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
17c40 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
17c50 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
17c60 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
17c70 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  r, .** [SQLITE_S
17c80 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61 20  CHEMA] is now a 
17c90 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
17ca0 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  lling.** [sqlite
17cb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17cc0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
17cd0 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
17ce0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
17cf0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
17d00 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
17d10 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
17d20 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
17d30 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
17d40 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
17d50 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44  MA] return. {END
17d60 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  }.** </li>.**.**
17d70 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
17d80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a   error occurs, .
17d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
17da0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
17db0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
17dc0 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  led .** [error c
17dd0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
17de0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
17df0 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20   .** The legacy 
17e00 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
17e10 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  t [sqlite3_step(
17e20 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
17e30 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a  turn a generic.*
17e40 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
17e50 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64   result code and
17e60 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
17e70 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
17e80 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
17e90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
17ea0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
17eb0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
17ec0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
17ed0 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  em..** With the 
17ee0 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74  "v2" prepare int
17ef0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
17f00 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
17f10 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a  or the error is.
17f20 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  ** returned imme
17f30 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
17f40 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
17f50 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
17f60 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68 65 20  ** {F13011} The 
17f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17f80 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
17f90 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
17fa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17fb0 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
17fc0 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
17fd0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
17fe0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
17ff0 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
18000 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
18010 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68 65 20  ** {F13012} The 
18020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18030 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
18040 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18050 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18060 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
18070 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
18080 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
18090 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
180a0 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
180b0 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
180c0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
180d0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
180e0 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74 68 65   {F13013} If the
180f0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
18100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
18110 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
18120 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
18130 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
18140 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
18150 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
18160 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20  SQL text is.**  
18170 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f          read fro
18180 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  m zSql is read u
18190 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
181a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
181b0 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49  **.** {F13014} I
181c0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
181d0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
181e0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
181f0 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
18200 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
18210 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
18220 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
18230 65 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  en nBytes bytes.
18240 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
18250 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f  text is read fro
18260 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  m zSql..**.** {F
18270 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74  13015} In [sqlit
18280 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
18290 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c  ,zSql,N,P,pzTail
182a0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
182b0 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nts.**          
182c0 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75  if the zSql inpu
182d0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
182e0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51  more than one SQ
182f0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20  L statement.**  
18300 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61          and pzTa
18310 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  il is not NULL, 
18320 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
18330 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
18340 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
18350 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
18360 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
18370 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
18380 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20  ent in zSql..** 
18390 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57           <todo>W
183a0 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c  hat does *pzTail
183b0 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65   point to if the
183c0 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d  re is one statem
183d0 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  ent?</todo>.**.*
183e0 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63  * {F13016} A suc
183f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
18400 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18410 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70  _v2(db,zSql,N,pp
18420 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Stmt,...)].**   
18430 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66         or one of
18440 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72   its variants wr
18450 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d  ites into *ppStm
18460 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
18470 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
18480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
18490 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74  ment] or a point
184a0 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20  er to NULL.**   
184b0 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20 63         if zSql c
184c0 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20  ontains nothing 
184d0 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65  other than white
184e0 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74  space or comment
184f0 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  s. .**.** {F1301
18500 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
18510 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e  prepare_v2()] in
18520 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20  terface and its 
18530 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a  variants return.
18540 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
18550 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70  ITE_OK] or an ap
18560 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
18570 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c   code] upon fail
18580 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
18590 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
185a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
185b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
185c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
185d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
185e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
185f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
18600 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
18610 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
18620 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
18630 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
18640 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
18650 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
18660 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
18670 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
18680 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
18690 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
186a0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
186b0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
186c0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
186d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
186e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
186f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
18700 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
18710 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
18720 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
18730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
18740 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
18750 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
18760 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
18770 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
18780 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
18790 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
187a0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
187b0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
187c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
187d0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
187e0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
187f0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
18800 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
18810 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
18820 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
18830 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
18840 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
18850 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
18860 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
18870 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
18880 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
18890 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
188a0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
188b0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
188c0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
188d0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
188e0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
188f0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
18900 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
18910 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
18920 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
18930 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
18940 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
18950 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
18960 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
18970 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
18980 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
18990 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
189a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
189b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
189c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
189d0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
189e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
189f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
18a00 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
18a10 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
18a20 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
18a30 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
18a40 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
18a50 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
18a60 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
18a70 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
18a80 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
18a90 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
18aa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20  ./*.** CAPIREF: 
18ab0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
18ac0 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30  ment SQL {F13100
18ad0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
18ae0 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 20 75  ereface can be u
18af0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
18b00 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
18b10 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
18b20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
18b30 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
18b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
18b50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
18b60 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d  :.**.** {F13101}
18b70 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
18b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
18b90 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
18ba0 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
18bb0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
18bc0 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
18bd0 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
18be0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
18bf0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
18c00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
18c10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18c20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
18c30 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  2()],.**        
18c40 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
18c50 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  sql()] function 
18c60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
18c70 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20  r to a.**       
18c80 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
18c90 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ed string contai
18ca0 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e  ning a UTF-8 ren
18cb0 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  dering.**       
18cc0 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e     of the origin
18cd0 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  al SQL statement
18ce0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d  ..**.** {F13102}
18cf0 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
18d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
18d10 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
18d20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
18d30 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
18d40 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
18d50 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
18d60 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
18d70 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
18d80 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
18d90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18da0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
18db0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
18dc0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
18dd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18de0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
18df0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d  ..**.** {F13103}
18e00 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
18e10 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
18e20 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
18e30 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20  d until the.**  
18e40 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
18e50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
18e60 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
18e70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
18e80 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  e(S)]..*/.const 
18e90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
18ea0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
18eb0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
18ec0 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69  API3REF:  Dynami
18ed0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
18ee0 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30 30  e Object  {F1500
18ef0 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
18f00 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
18f10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
18f20 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
18f30 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
18f40 65 20 6f 72 20 63 61 6e 20 62 65 20 73 74 6f 72  e or can be stor
18f50 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
18f60 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74   table..** SQLit
18f70 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
18f80 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61  yping for the va
18f90 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
18fa0 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f 72   .** Values stor
18fb0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
18fc0 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61 6e 20  lue objects can 
18fd0 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72  be.** be integer
18fe0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
18ff0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
19000 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
19010 4c 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  L..*/.typedef st
19020 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
19030 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
19040 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75  API3REF:  SQL Fu
19050 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
19060 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a  bject {F16001}.*
19070 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
19080 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
19090 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
190a0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
190b0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
190c0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41  ntext object.  A
190d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
190e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
190f0 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61  * object is alwa
19100 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
19110 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
19120 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
19130 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65  nctions..*/.type
19140 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
19150 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
19160 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
19170 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42 69  ** CAPI3REF:  Bi
19180 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
19190 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
191a0 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a  nts {F13500}.**.
191b0 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74  ** In the SQL st
191c0 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b  rings input to [
191d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
191e0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a  v2()] and its.**
191f0 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74 65 72   variants, liter
19200 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
19210 63 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65  ce by a paramete
19220 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74  r in one.** of t
19230 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a  hese forms:.**.*
19240 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
19250 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
19260 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
19270 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
19280 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
19290 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
192a0 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20  parameter forms 
192b0 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20  shown above NNN 
192c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  is an integer li
192d0 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c  teral,.** VVV al
192e0 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
192f0 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54  meter name..** T
19300 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
19310 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  se parameters (a
19320 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
19330 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
19340 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70 61 72  ".** or "SQL par
19350 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
19360 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
19370 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
19380 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
19390 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
193a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
193b0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
193c0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
193d0 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73  nes always.** is
193e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
193f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
19400 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
19410 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
19420 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
19430 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
19440 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   The second.** a
19450 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
19460 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72 61  ndex of the para
19470 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
19480 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61   The.** first pa
19490 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
194a0 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e  ndex of 1.  When
194b0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
194c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
194d0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
194e0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
194f0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
19500 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
19510 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
19520 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
19530 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69  rence. .** The i
19540 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
19550 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
19560 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
19570 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19580 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
19590 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64  name()] API if d
195a0 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
195b0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
195c0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
195d0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
195e0 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
195f0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
19600 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70  n 1 and the comp
19610 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61  ile-time.** para
19620 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58  meter SQLITE_MAX
19630 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
19640 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
19650 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   999)..**.** The
19660 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19670 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
19680 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
19690 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  meter..**.** In 
196a0 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  those.** routine
196b0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
196c0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
196d0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  ts value is the 
196e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
196f0 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ** in the parame
19700 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
19710 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
19720 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  the number of <u
19730 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e  >bytes</u>.** in
19740 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
19750 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
19760 61 72 61 63 74 65 72 73 2e 20 20 20 54 68 65 20  aracters.   The 
19770 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
19780 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  es does not incl
19790 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  ude the zero-ter
197a0 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
197b0 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a  nd of strings..*
197c0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
197d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
197e0 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
197f0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
19800 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  is.** number of 
19810 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
19820 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
19830 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
19840 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
19850 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
19860 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
19870 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
19880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
19890 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
198a0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
198b0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
198c0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
198d0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
198e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
198f0 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66  h it. If the fif
19900 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
19910 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
19920 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
19930 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
19940 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
19950 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
19960 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
19970 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
19980 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
19990 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
199a0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
199b0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
199c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
199d0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
199e0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
199f0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
19a00 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
19a10 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
19a20 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
19a30 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
19a40 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
19a50 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
19a60 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
19a70 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
19a80 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
19a90 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
19aa0 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
19ab0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
19ac0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
19ad0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
19ae0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
19af0 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69 6c  ld it size) whil
19b00 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
19b10 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
19b20 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
19b30 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
19b40 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72  lace-holders for
19b50 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
19b60 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
19b70 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20 0a   written using .
19b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
19b90 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
19ba0 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  t BLOB I/O] rout
19bb0 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69 76 65  ines. A negative
19bc0 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 74 68  .** value for th
19bd0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
19be0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
19bf0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
19c00 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
19c10 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75  _*() routines mu
19c20 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74  st be called aft
19c30 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
19c40 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e  repare_v2()] (an
19c50 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  d its variants) 
19c60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
19c70 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f  t()] and.** befo
19c80 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
19c90 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73  ()]..** Bindings
19ca0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
19cb0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
19cc0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
19cd0 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61  e..** Unbound pa
19ce0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
19cf0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
19d00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
19d10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
19d20 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
19d30 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72  cess or an error
19d40 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74   code if.** anyt
19d50 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
19d60 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d    [SQLITE_RANGE]
19d70 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
19d80 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
19d90 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
19da0 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45   range.  [SQLITE
19db0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
19dc0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61  ned if malloc fa
19dd0 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ils..** [SQLITE_
19de0 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65  MISUSE] might be
19df0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
19e00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19e10 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76  called on a.** v
19e20 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74  irtual machine t
19e30 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67  hat is the wrong
19e40 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20   state or which 
19e50 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e  has already been
19e60 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44   finalized..** D
19e70 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75  etection of misu
19e80 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65  se is unreliable
19e90 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
19ea0 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e  should not depen
19eb0 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d  d.** on SQLITE_M
19ec0 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20  ISUSE returns.  
19ed0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73  SQLITE_MISUSE is
19ee0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64   intended to ind
19ef0 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67  icate a.** a log
19f00 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  ic error in the 
19f10 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75  application.  Fu
19f20 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
19f30 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
19f40 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68   panic rather th
19f50 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  an return SQLITE
19f60 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53  _MISUSE..**.** S
19f70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
19f80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
19f90 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
19fa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
19fb0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
19fc0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
19fd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
19fe0 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
19ff0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1a000 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71  {F13506} The [sq
1a010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1a020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1a030 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a  mpiler] recogniz
1a040 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
1a050 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
1a060 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  ms "?", "?NNN", 
1a070 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20  "$VVV", ":VVV", 
1a080 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20  and "@VVV".**   
1a090 20 20 20 20 20 20 20 61 73 20 53 51 4c 20 70 61         as SQL pa
1a0a0 72 61 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20  rameters, where 
1a0b0 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65  NNN is any seque
1a0c0 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
1a0d0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  re.**          d
1a0e0 69 67 69 74 73 20 61 6e 64 20 77 68 65 72 65 20  igits and where 
1a0f0 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65  VVV is any seque
1a100 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
1a110 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  re .**          
1a120 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61  alphanumeric cha
1a130 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20  racters or "::" 
1a140 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f  optionally follo
1a150 77 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  wed by.**       
1a160 20 20 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74     a string cont
1a170 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73  aining no spaces
1a180 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77   and contained w
1a190 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65  ithin parenthese
1a1a0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39  s..**.** {F13509
1a1b0 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61  } The initial va
1a1c0 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  lue of an SQL pa
1a1d0 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e  rameter is NULL.
1a1e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20  .**.** {F13512} 
1a1f0 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
1a200 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  "?" SQL paramete
1a210 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20  r is one larger 
1a220 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  than the.**     
1a230 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64       largest ind
1a240 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
1a250 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c  ter to the left,
1a260 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20   or 1 if.**     
1a270 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20       the "?" is 
1a280 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  the leftmost SQL
1a290 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1a2a0 2a 20 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69  * {F13515} The i
1a2b0 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e  ndex of an "?NNN
1a2c0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
1a2d0 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e  is the integer N
1a2e0 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31  NN..**.** {F1351
1a2f0 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  8} The index of 
1a300 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56  an ":VVV", "$VVV
1a310 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c  ", or "@VVV" SQL
1a320 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1a330 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
1a340 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20  me as the index 
1a350 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75  of leftmost occu
1a360 72 61 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61  rances of the sa
1a370 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  me.**          p
1a380 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65  arameter, or one
1a390 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c   more than the l
1a3a0 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65  argest index ove
1a3b0 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  r all.**        
1a3c0 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20    parameters to 
1a3d0 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73  the left if this
1a3e0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   is the first oc
1a3f0 63 75 72 72 61 6e 63 65 0a 2a 2a 20 20 20 20 20  currance.**     
1a400 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72       of this par
1a410 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20  ameter, or 1 if 
1a420 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74  this is the left
1a430 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  most parameter..
1a440 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54  **.** {F13521} T
1a450 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1a460 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d  are | SQL statem
1a470 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
1a480 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  il with.**      
1a490 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52      an [SQLITE_R
1a4a0 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20 74  ANGE] error if t
1a4b0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1a4c0 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  QL parameter.** 
1a4d0 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73 73           is less
1a4e0 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61 74   than 1 or great
1a4f0 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d  er than SQLITE_M
1a500 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1a510 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32  ER..**.** {F1352
1a520 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  4} Calls to [sql
1a530 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1a540 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
1a550 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,V,...)].**    
1a560 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20        associate 
1a570 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68  the value V with
1a580 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74   all SQL paramet
1a590 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a  ers having an.**
1a5a0 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20            index 
1a5b0 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65  of N in the [pre
1a5c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1a5d0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32   S..**.** {F1352
1a5e0 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  7} Calls to [sql
1a5f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1a600 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
1a610 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
1a620 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69      override pri
1a630 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68  or calls with th
1a640 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66  e same values of
1a650 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20   S and N..**.** 
1a660 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67  {F13530} Binding
1a670 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79  s established by
1a680 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1a690 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
1a6a0 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  nd(S,...)].**   
1a6b0 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61         persist a
1a6c0 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b  cross calls to [
1a6d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
1a6e0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33  ]..**.** {F13533
1a6f0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1a700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1a710 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1a720 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a730 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1a740 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1a750 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a760 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1a770 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
1a780 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74   binds the first
1a790 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   L.**          b
1a7a0 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62  ytes of the blob
1a7b0 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74   or string point
1a7c0 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e  ed to by V, when
1a7d0 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   L.**          i
1a7e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
1a7f0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49  **.** {F13536} I
1a800 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1a810 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
1a820 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20  N,V,L,D)] or.** 
1a830 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a840 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1a850 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
1a860 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72   binds character
1a870 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  s.**          fr
1a880 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65  om V through the
1a890 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
1a8a0 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20  acter when L is 
1a8b0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
1a8c0 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c  {F13539} In call
1a8d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1a8e0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
1a8f0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
1a900 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1a910 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
1a920 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1a930 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1a940 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
1a950 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73   when D is the s
1a960 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  pecial.**       
1a970 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c     constant [SQL
1a980 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c  ITE_STATIC], SQL
1a990 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
1a9a0 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20   the value V.** 
1a9b0 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64           is held
1a9c0 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e   in static unman
1a9d0 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20  aged space that 
1a9e0 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a  will not change.
1a9f0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69  **          duri
1aa00 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
1aa10 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a  of the binding..
1aa20 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49  **.** {F13542} I
1aa30 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1aa40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
1aa50 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
1aa60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1aa70 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
1aa80 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
1aa90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
1aaa0 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
1aab0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
1aac0 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20   the special.** 
1aad0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e           constan
1aae0 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  t [SQLITE_TRANSI
1aaf0 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e  ENT], the routin
1ab00 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20  e makes a .**   
1ab10 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63         private c
1ab20 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20 62  opy of V value b
1ab30 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
1ab40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d  ..**.** {F13545}
1ab50 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1ab60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1ab70 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
1ab80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1ab90 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1aba0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
1abb0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1abc0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
1abd0 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
1abe0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
1abf0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75  **          a fu
1ac00 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69  nction, SQLite i
1ac10 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63  nvokes that func
1ac20 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20  tion to destroy 
1ac30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1ac40 56 20 76 61 6c 75 65 20 61 66 74 65 72 20 69 74  V value after it
1ac50 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
1ac60 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ing the V value.
1ac70 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20  .**.** {F13548} 
1ac80 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1ac90 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1aca0 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65  ob(S,N,V,L)] the
1acb0 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20   value bound.** 
1acc0 20 20 20 20 20 20 20 20 20 69 73 20 61 20 62 6c           is a bl
1acd0 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f  ob of L bytes, o
1ace0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
1acf0 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65 67  blob if L is neg
1ad00 61 74 69 76 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ative..*/.int sq
1ad10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1ad20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1ad30 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
1ad40 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1ad50 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1ad60 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
1ad70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1ad80 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
1ad90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1ada0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1adb0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
1adc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
1add0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
1ade0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
1adf0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
1ae00 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
1ae10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ae20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1ae30 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
1ae40 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1ae50 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
1ae60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1ae70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1ae80 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
1ae90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1aea0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
1aeb0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1aec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1aed0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
1aee0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1aef0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
1af00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1af10 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
1af20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1af30 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1af40 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
1af50 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
1af60 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a  rs {F13600}.**.*
1af70 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
1af80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
1af90 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
1afa0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 0a   SQL parameters.
1afb0 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72 65 64  ** in a prepared
1afc0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 51 4c   statement.  SQL
1afd0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1afe0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
1aff0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
1b000 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
1b010 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
1b020 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
1b030 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20  ace-holders for 
1b040 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
1b050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1b060 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
1b070 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
1b080 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
1b090 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
1b0a0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
1b0b0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
1b0c0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  of the largest p
1b0d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46 6f 72  arameter..** For
1b0e0 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
1b0f0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
1b100 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
1b110 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1b120 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
1b130 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
1b140 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61  rs of the ?NNN a
1b150 72 65 20 75 73 65 64 2c 20 74 68 65 72 65 20 6d  re used, there m
1b160 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20 69 6e  ay.** be gaps in
1b170 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a   the list..**.**
1b180 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1b190 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1b1a0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1b1b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1b1c0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1b1d0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1b1e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b1f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1b200 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1b210 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54 68 65  .** {F13601} The
1b220 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1b230 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53  arameter_count(S
1b240 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1b250 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
1b260 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
1b270 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61  ex of all SQL pa
1b280 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a  rameters in the.
1b290 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1b2a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1b2b0 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a 2a 2a   S, or 0 if S.**
1b2c0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69            contai
1b2d0 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  ns no SQL parame
1b2e0 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ters..*/.int sql
1b2f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1b300 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
1b310 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1b320 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
1b330 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
1b340 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a  ter {F13620}.**.
1b350 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1b360 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1b370 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
1b380 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53 51 4c   the n-th.** SQL
1b390 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20   parameter in a 
1b3a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1b3b0 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
1b3c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1b3d0 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20 22 40  orm ":AAA" or "@
1b3e0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 20 68  AAA" or "$AAA" h
1b3f0 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20 77 68  ave a name.** wh
1b400 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
1b410 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  g ":AAA" or "@AA
1b420 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20 0a 2a  A" or "$VVV". .*
1b430 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
1b440 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
1b450 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 0a  " or "$" or "@".
1b460 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
1b470 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
1b480 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72  me..** Parameter
1b490 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
1b4a0 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61 76 65  " or "?NNN" have
1b4b0 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20   no name..**.** 
1b4c0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
1b4d0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1b4e0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
1b4f0 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
1b500 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
1b510 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
1b520 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
1b530 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
1b540 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
1b550 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
1b560 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
1b570 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65  ** always in the
1b580 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1b590 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
1b5a0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
1b5b0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
1b5c0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
1b5d0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
1b5e0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
1b5f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b600 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1b610 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1b620 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1b630 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1b640 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1b650 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1b660 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1b670 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1b680 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1b690 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1b6a0 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54 68  *.** {F13621} Th
1b6b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1b6c0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53  parameter_name(S
1b6d0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1b6e0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1b6f0 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65     a UTF-8 rende
1b700 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65  ring of the name
1b710 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
1b720 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20  meter in.**     
1b730 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1b740 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69  tatement] S havi
1b750 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a  ng index N, or.*
1b760 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  *          NULL 
1b770 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53  if there is no S
1b780 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  QL parameter wit
1b790 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20  h index N or if 
1b7a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1b7b0 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
1b7c0 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f  ndex N is an ano
1b7d0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
1b7e0 20 22 3f 22 20 6f 72 0a 2a 2a 20 20 20 20 20 20   "?" or.**      
1b7f0 20 20 20 20 61 20 6e 75 6d 62 65 72 65 64 20 70      a numbered p
1b800 61 72 61 6d 65 74 65 72 20 22 3f 4e 4e 4e 22 2e  arameter "?NNN".
1b810 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1b820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1b830 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
1b840 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1b850 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b860 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
1b870 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
1b880 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36 34 30  ven Name {F13640
1b890 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
1b8a0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1b8b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
1b8c0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
1b8d0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
1b8e0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
1b8f0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
1b900 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
1b910 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1b920 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1b930 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
1b940 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
1b950 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
1b960 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
1b970 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
1b980 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
1b990 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
1b9a0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
1b9b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1b9c0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
1b9d0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
1b9e0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
1b9f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ba00 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
1ba10 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1ba20 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1ba30 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1ba40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1ba50 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1ba60 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1ba70 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ba80 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1ba90 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1baa0 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65 20 5b  * {F13641} The [
1bab0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1bac0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e  ameter_index(S,N
1bad0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1bae0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
1baf0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51   the index of SQ
1bb00 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 5b  L parameter in [
1bb10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1bb20 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
1bb30 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74  S whose name mat
1bb40 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73  ches the UTF-8 s
1bb50 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66  tring N, or 0 if
1bb60 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20   there is.**    
1bb70 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a        no match..
1bb80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1bb90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1bba0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
1bbb0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
1bbc0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
1bbd0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
1bbe0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
1bbf0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
1bc00 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a  nt {F13660}.**.*
1bc10 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68  * Contrary to th
1bc20 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
1bc30 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
1bc40 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a  set()] does not.
1bc50 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b 73 71  ** reset the [sq
1bc60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1bc70 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
1bc80 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
1bc90 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73 65 20  tatement].  Use 
1bca0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a  this routine to.
1bcb0 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  ** reset all hos
1bcc0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
1bcd0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  NULL..**.** INVA
1bce0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1bcf0 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  13661} The [sqli
1bd00 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1bd10 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  gs(S)] interface
1bd20 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a 20 20   resets all.**  
1bd30 20 20 20 20 20 20 20 20 53 51 4c 20 70 61 72 61          SQL para
1bd40 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69  meter bindings i
1bd50 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
1bd60 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
1bd70 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e 55 4c       back to NUL
1bd80 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
1bd90 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
1bda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1bdb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bdc0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
1bdd0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
1bde0 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a  Set {F13710}.**.
1bdf0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
1be00 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1be10 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1be20 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
1be30 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
1be40 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73  statement]. This
1be50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1be60 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20 69   0.** if pStmt i
1be70 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  s an SQL stateme
1be80 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
1be90 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
1bea0 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61 6e  r .** example an
1beb0 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a 2a 20   UPDATE)..**.** 
1bec0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1bed0 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65 20 5b  * {F13711} The [
1bee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
1bef0 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61  ount(S)] interfa
1bf00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1bf10 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
1bf20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20       columns in 
1bf30 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 67  the result set g
1bf40 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65 0a  enerated by the.
1bf50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1bf60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1bf70 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 64 6f   S, or 0 if S do
1bf80 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 0a  es not generate.
1bf90 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
1bfa0 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  sult set..*/.int
1bfb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1bfc0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
1bfd0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1bfe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
1bff0 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
1c000 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 32  esult Set {F1372
1c010 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
1c020 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1c030 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
1c040 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
1c050 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
1c060 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
1c070 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
1c080 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
1c090 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
1c0a0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
1c0b0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c0c0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c0d0 65 64 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  ed UTF8 string.*
1c0e0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
1c0f0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
1c100 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c110 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1c120 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20 73 74  ated.** UTF16 st
1c130 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74  ring.  The first
1c140 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1c150 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1c160 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1c170 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53 45  mplements the SE
1c180 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1c190 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1c1a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63  rameter is the c
1c1b0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54  olumn number.  T
1c1c0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
1c1d0 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72  umn is.** number
1c1e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65   0..**.** The re
1c1f0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
1c200 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
1c210 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
1c220 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1c230 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
1c240 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
1c250 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
1c260 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
1c270 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  xt call sqlite3_
1c280 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
1c290 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1c2a0 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74  name16().** on t
1c2b0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
1c2c0 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
1c2d0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
1c2e0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
1c2f0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
1c300 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
1c310 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
1c320 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
1c330 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
1c340 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
1c350 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1c360 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1c370 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
1c380 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
1c390 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
1c3a0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
1c3b0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
1c3c0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
1c3d0 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
1c3e0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
1c3f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
1c400 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
1c410 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
1c420 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
1c430 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
1c440 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
1c450 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  e next..**.** IN
1c460 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c470 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63 63 65  {F13721} A succe
1c480 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
1c490 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1c4a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
1c4b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
1c4c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1c4d0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
1c4e0 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e 74 68        of the Nth
1c4f0 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30   column (where 0
1c500 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73   is the left-mos
1c510 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
1c520 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
1c530 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
1c540 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c550 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20   S as a.**      
1c560 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1c570 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1c580 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 33 7d  ..**.** {F13723}
1c590 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
1c5a0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
1c5b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c5c0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20  name16(S,N)].** 
1c5d0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
1c5e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1c5f0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
1c600 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  of the Nth colum
1c610 6e 20 28 77 68 65 72 65 20 30 20 69 73 20 74 68  n (where 0 is th
1c620 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
1c630 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  mn) for the.**  
1c640 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
1c650 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
1c660 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
1c670 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
1c680 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1c690 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 74  F-16 string in t
1c6a0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1c6b0 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  rder..**.** {F13
1c6c0 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  724} The [sqlite
1c6d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
1c6e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
1c6f0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a  lumn_name16()].*
1c700 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1c710 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e  faces return a N
1c720 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74  ULL pointer if t
1c730 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74  hey are unable t
1c740 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  o.**          al
1c750 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 6d 65  locate memory me
1c760 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1c770 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e  re normal return
1c780 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20   strings..**.** 
1c790 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68 65 20  {F13725} If the 
1c7a0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  N parameter to [
1c7b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1c7c0 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  ame(S,N)] or.** 
1c7d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c7e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1c7f0 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20  S,N)] is out of 
1c800 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a  range, then the.
1c810 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1c820 72 66 61 63 65 73 20 72 65 74 75 72 6e 73 20 61  rfaces returns a
1c830 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1c840 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54  * .** {F13726} T
1c850 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1c860 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1c870 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
1c880 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
1c890 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
1c8a0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61  n_name16(S,N)] a
1c8b0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
1c8c0 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20  he next.**      
1c8d0 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68      call to eith
1c8e0 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  er routine with 
1c8f0 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e  the same S and N
1c900 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
1c910 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
1c920 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1c930 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
1c940 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d  ..**.** {F13727}
1c950 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63   When a result c
1c960 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45  olumn of a [SELE
1c970 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
1c980 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
1c990 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c     an AS clause,
1c9a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61   the name of tha
1c9b0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
1c9c0 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20  indentifier.**  
1c9d0 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72          to the r
1c9e0 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b  ight of the AS k
1c9f0 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  eyword..*/.const
1ca00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1ca10 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
1ca20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
1ca30 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1ca40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1ca50 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1ca60 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
1ca70 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
1ca80 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
1ca90 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31  Query Result {F1
1caa0 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3740}.**.** Thes
1cab0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
1cac0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
1cad0 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
1cae0 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
1caf0 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
1cb00 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
1cb10 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
1cb20 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
1cb30 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
1cb40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
1cb50 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
1cb60 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
1cb70 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
1cb80 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74  UTF8 or UTF16 st
1cb90 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
1cba0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
1cbb0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
1cbc0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
1cbd0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
1cbe0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
1cbf0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
1cc00 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
1cc10 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
1cc20 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
1cc30 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1cc40 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
1cc50 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70 61 72  l.** the [prepar
1cc60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
1cc70 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67   destroyed using
1cc80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
1cc90 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
1cca0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
1ccb0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
1ccc0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
1ccd0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
1cce0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ding..**.** The 
1ccf0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
1cd00 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
1cd10 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
1cd20 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
1cd30 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
1cd40 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  column..**.** Th
1cd50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1cd60 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
1cd70 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72  g calls is a [pr
1cd80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cd90 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  ]..** These func
1cda0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
1cdb0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
1cdc0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
1cdd0 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68  turned by .** th
1cde0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
1cdf0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1ce00 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
1ce10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ment..**.** If t
1ce20 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
1ce30 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
1ce40 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
1ce50 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73  pression.** or s
1ce60 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
1ce70 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
1ce80 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
1ce90 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hese functions.*
1cea0 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 20  * return NULL.  
1ceb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
1cec0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
1ced0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
1cee0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  .** allocation e
1cef0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 4f 74  rror occurs.  Ot
1cf00 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
1cf10 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d  turn the .** nam
1cf20 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
1cf30 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
1cf40 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61  e and column tha
1cf50 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  t query result.*
1cf60 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  * column was ext
1cf70 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
1cf80 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  ** As with all o
1cf90 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
1cfa0 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65  , those postfixe
1cfb0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
1cfc0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
1cfd0 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68  oded strings, th
1cfe0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
1cff0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20  s return UTF-8. 
1d000 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
1d010 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
1d020 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
1d030 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
1d040 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 0a  piled with the .
1d050 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
1d060 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
1d070 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
1d080 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
1d090 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20  .** {U13751}.** 
1d0a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
1d0b0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
1d0c0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
1d0d0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
1d0e0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
1d0f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d100 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
1d110 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
1d120 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
1d130 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
1d140 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1d150 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d  :.**.** {F13741}
1d160 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1d170 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1d180 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
1d190 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1d1a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1d1b0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
1d1c0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
1d1d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
1d1e0 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
1d1f0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
1d200 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
1d210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d220 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
1d230 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
1d240 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74  or NULL if the t
1d250 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1d260 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
1d270 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
1d280 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
1d290 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1d2a0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
1d2b0 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
1d2c0 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
1d2d0 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d 20 54    .** {F13742} T
1d2e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1d2f0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1d300 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
1d310 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1d320 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1d330 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
1d340 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
1d350 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1d360 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1d370 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
1d380 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
1d390 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
1d3a0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
1d3b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d3c0 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
1d3d0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
1d3e0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74 68  r NULL if the th
1d3f0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
1d400 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
1d410 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
1d420 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
1d430 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1d440 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
1d450 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
1d460 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
1d470 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20 54 68   .** {F13743} Th
1d480 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1d490 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
1d4a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1d4b0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
1d4c0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
1d4d0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1d4e0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
1d4f0 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
1d500 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1d510 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
1d520 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
1d530 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
1d540 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
1d550 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
1d560 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f  f the the Nth co
1d570 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
1d580 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
1d590 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
1d5a0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
1d5b0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
1d5c0 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
1d5d0 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
1d5e0 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
1d5f0 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3744} The [sqlit
1d600 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1d610 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
1d620 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
1d630 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
1d640 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
1d650 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
1d660 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
1d670 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1d680 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f  of the table fro
1d690 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
1d6a0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
1d6b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
1d6c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d6d0 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
1d6e0 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
1d6f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74  or NULL if the t
1d700 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1d710 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
1d720 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
1d730 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
1d740 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1d750 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
1d760 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
1d770 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
1d780 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54    .** {F13745} T
1d790 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1d7a0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
1d7b0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1d7c0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
1d7d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
1d7e0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1d7f0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1d800 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
1d810 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
1d820 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
1d830 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
1d840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d850 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
1d860 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
1d870 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74  or NULL if the t
1d880 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1d890 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
1d8a0 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
1d8b0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
1d8c0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1d8d0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
1d8e0 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
1d8f0 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
1d900 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54    .** {F13746} T
1d910 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1d920 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
1d930 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1d940 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
1d950 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1d960 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
1d970 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
1d980 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
1d990 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
1d9a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72   table column fr
1d9b0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
1d9c0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
1d9d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
1d9e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d9f0 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
1da00 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
1da10 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
1da20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1da30 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
1da40 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
1da50 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
1da60 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1da70 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
1da80 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
1da90 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
1daa0 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38 7d 20     .** {F13748} 
1dab0 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
1dac0 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
1dad0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
1dae0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1daf0 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61  |column metadata
1db00 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
1db10 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
1db20 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  id.**          f
1db30 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  or the lifetime 
1db40 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
1db50 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
1db60 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
1db70 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
1db80 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74   changed by anot
1db90 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  her metadata.** 
1dba0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
1dbb0 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20  ce call for the 
1dbc0 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74  same prepared st
1dbd0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
1dbe0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  mn..**.** LIMITA
1dbf0 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
1dc00 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20  3751} If two or 
1dc10 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
1dc20 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
1dc30 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1dc40 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1dc50 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d  se_name|column m
1dc60 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
1dc70 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
1dc80 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
1dc90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
1dca0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
1dcb0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
1dcc0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
1dcd0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
1dce0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
1dcf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1dd00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1dd10 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
1dd20 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1dd30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1dd40 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1dd50 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1dd60 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1dd70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1dd80 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
1dd90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1dda0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
1ddb0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1ddc0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
1ddd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1dde0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1ddf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
1de00 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
1de10 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1de20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1de30 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
1de40 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1de50 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
1de60 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
1de70 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
1de80 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
1de90 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13760}.**.** Th
1dea0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1deb0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
1dec0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a   statement]. .**
1ded0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
1dee0 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73  nt is a SELECT s
1def0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
1df00 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
1df10 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  he .** returned 
1df20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
1df30 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74  at SELECT is a t
1df40 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
1df50 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
1df60 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
1df70 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
1df80 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
1df90 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
1dfa0 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68  returned.  If th
1dfb0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
1dfc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
1dfd0 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
1dfe0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
1dff0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
1e000 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
1e010 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
1e020 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
1e030 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
1e040 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f 72 20    {END} .** For 
1e050 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65 20  example, in the 
1e060 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
1e070 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
1e080 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
1e090 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68  T);.**.** And th
1e0a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
1e0b0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a  ement compiled:.
1e0c0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
1e0d0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
1e0e0 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73  .**.** Then this
1e0f0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
1e100 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
1e110 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
1e120 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73  he second.** res
1e130 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  ult column (i==1
1e140 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
1e150 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
1e160 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
1e170 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  n.** (i==0)..**.
1e180 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
1e190 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
1e1a0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
1e1b0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
1e1c0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
1e1d0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
1e1e0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
1e1f0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
1e200 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
1e210 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
1e220 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
1e230 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
1e240 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
1e250 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
1e260 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
1e270 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
1e280 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
1e290 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
1e2a0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
1e2b0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
1e2c0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
1e2d0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
1e2e0 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ues..**.** INVAR
1e2f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1e300 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73  3761}  A success
1e310 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1e320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1e330 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  type(S,N)].**   
1e340 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
1e350 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1e360 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
1e370 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
1e380 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64             the d
1e390 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65  eclared datatype
1e3a0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1e3b0 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
1e3c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  s.**           a
1e3d0 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  s the Nth column
1e3e0 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20   (numbered from 
1e3f0 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
1e400 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20   set to the.**  
1e410 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1e420 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
1e430 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32 7d 20  .**.** {F13762} 
1e440 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1e450 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1e460 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
1e470 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
1e480 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65      returns a ze
1e490 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1e4a0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
1e4b0 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a   order string.**
1e4c0 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61             conta
1e4d0 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72  ining the declar
1e4e0 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ed datatype of t
1e4f0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1e500 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20  that appears.** 
1e510 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
1e520 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
1e530 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66  bered from 0) of
1e540 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1e550 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1e560 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
1e570 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
1e580 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66 20 4e  * {F13763}  If N
1e590 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20   is less than 0 
1e5a0 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72 20  or N is greater 
1e5b0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1e5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
1e5d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1e5e0 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64  mns in [prepared
1e5f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
1e600 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66             or if
1e610 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1e620 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65  of S is an expre
1e630 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
1e640 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20  y rather.**     
1e650 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62        than a tab
1e660 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69 66 20  le column or if 
1e670 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1e680 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20  ion failure.**  
1e690 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
1e6a0 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  during encoding 
1e6b0 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65  conversions, the
1e6c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  n.**           c
1e6d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1e6e0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
1e6f0 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
1e700 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1e710 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
1e720 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e  6(S,N)] return N
1e730 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ULL..*/.const ch
1e740 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1e750 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
1e760 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1e770 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1e780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
1e790 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
1e7a0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a  mt*,int);../* .*
1e7b0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61  * CAPI3REF:  Eva
1e7c0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
1e7d0 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30 7d 0a  tement {F13200}.
1e7e0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b  **.** After an [
1e7f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e800 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
1e810 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c  pared with a cal
1e820 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b  l.** to either [
1e830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e840 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1e850 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e860 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a  ] or to one of.*
1e870 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  * the legacy int
1e880 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
1e890 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
1e8a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e8b0 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  6()],.** then th
1e8c0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  is function must
1e8d0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
1e8e0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1e8f0 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a  evaluate the .**
1e900 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
1e910 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
1e920 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
1e930 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74   this sqlite3_st
1e940 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
1e950 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
1e960 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
1e970 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
1e980 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
1e990 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
1e9a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e9b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1e9c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e9d0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
1e9e0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
1e9f0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
1ea00 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
1ea10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ea20 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
1ea30 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
1ea40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
1ea50 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
1ea60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
1ea70 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
1ea80 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
1ea90 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
1eaa0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
1eab0 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e  In the lagacy in
1eac0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
1ead0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
1eae0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
1eaf0 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  _BUSY], .** [SQL
1eb00 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
1eb10 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
1eb20 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
1eb30 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
1eb40 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
1eb50 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
1eb60 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54  the other [SQLIT
1eb70 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
1eb80 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  de].** or [SQLIT
1eb90 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
1eba0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ebb0 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65  ode] might be re
1ebc0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c  turned as.** wel
1ebd0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
1ebe0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
1ebf0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
1ec00 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
1ec10 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
1ec20 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
1ec30 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
1ec40 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
1ec50 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
1ec60 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63   COMMIT.** or oc
1ec70 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
1ec80 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1ec90 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
1eca0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
1ecb0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
1ecc0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1ecd0 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20  is not a COMMIT 
1ece0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
1ecf0 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
1ed00 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
1ed10 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
1ed20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
1ed30 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
1ed40 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
1ed50 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
1ed60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
1ed70 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
1ed80 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
1ed90 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
1eda0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1edb0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
1edc0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
1edd0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
1ede0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
1edf0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
1ee00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
1ee10 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
1ee20 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
1ee30 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
1ee40 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
1ee50 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1ee60 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
1ee70 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
1ee80 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53  ata, then .** [S
1ee90 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65  QLITE_ROW] is re
1eea0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
1eeb0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
1eec0 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66  ta is ready.** f
1eed0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
1eee0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65   the caller. The
1eef0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
1ef00 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a  ccessed using.**
1ef10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1ef20 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d  lumn_int | colum
1ef30 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
1ef40 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
1ef50 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
1ef60 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
1ef70 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
1ef80 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20  of data..** .** 
1ef90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
1efa0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
1efb0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
1efc0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
1efd0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
1efe0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
1eff0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
1f000 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
1f010 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
1f020 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
1f030 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
1f040 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
1f050 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f060 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c  ]..** With the l
1f070 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
1f080 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
1f090 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
1f0a0 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple:.** [SQLITE
1f0b0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
1f0c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
1f0d0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
1f0e0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
1f0f0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
1f100 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1f110 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
1f120 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1f130 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
1f140 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
1f150 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
1f160 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
1f170 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
1f180 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
1f190 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
1f1a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
1f1b0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
1f1c0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
1f1d0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
1f1e0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
1f1f0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
1f200 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
1f210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1f220 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
1f230 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
1f240 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
1f250 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
1f260 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70 72   that had .** pr
1f270 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1f280 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
1f290 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
1f2a0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
1f2b0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
1f2c0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
1f2d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f2e0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
1f2f0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
1f300 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
1f310 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
1f320 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ime..**.** <b>Go
1f330 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
1f340 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74  ert:</b>.** In t
1f350 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
1f360 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c  ace, .** the sql
1f370 69 74 65 33 5f 73 74 65 70 28 29 20 41 50 49 20  ite3_step() API 
1f380 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
1f390 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
1f3a0 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ode,.** [SQLITE_
1f3b0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
1f3c0 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68 65  g any error othe
1f3d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
1f3e0 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  USY].** and [SQL
1f3f0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
1f400 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c  u must call [sql
1f410 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
1f420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
1f430 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
1f440 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
1f450 20 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a 2a   the specific.**
1f460 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
1f470 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
1f480 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
1f490 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
1f4a0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
1f4b0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
1f4c0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
1f4d0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
1f4e0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
1f4f0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
1f500 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
1f510 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
1f520 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1f530 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f540 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1f550 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
1f560 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
1f570 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
1f580 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
1f590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f5a0 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
1f5b0 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66 69  .** more specifi
1f5c0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
1f5d0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
1f5e0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
1f5f0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
1f600 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
1f610 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
1f620 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1f630 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1f640 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 66 20  ** {F13202}  If 
1f650 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f660 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
1f670 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  to be.**        
1f680 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b 73 71     run, then [sq
1f690 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
1f6a0 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
1f6b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
1f6c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75 6e 74  **           unt
1f6d0 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  il to completion
1f6e0 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20   or until it is 
1f6f0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20  ready to return 
1f700 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20 20 20  another.**      
1f710 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68 65 20       row of the 
1f720 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20 61 6e  result set or an
1f730 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20 72 75   interrupt or ru
1f740 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63  n-time error occ
1f750 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  urs..**.** {F153
1f760 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c  04}  When a call
1f770 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
1f780 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 65  p(S)] causes the
1f790 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b   .**           [
1f7a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f7b0 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74 6f 20  nt] S to run to 
1f7c0 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a 20 20  completion,.**  
1f7d0 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e           the fun
1f7e0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
1f7f0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a  QLITE_DONE]..**.
1f800 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57 68 65  ** {F15306}  Whe
1f810 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
1f820 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74  ite3_step(S)] st
1f830 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69  ops because it i
1f840 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20 20 20  s ready.**      
1f850 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e 20 61       to return a
1f860 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
1f870 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74  e result set, it
1f880 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1f890 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
1f8a0 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30  W]..**.** {F1530
1f8b0 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  8}  If a call to
1f8c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
1f8d0 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  )] encounters an
1f8e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
1f8f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1f900 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61  |interrupt] or a
1f910 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
1f920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
1f930 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
1f940 6f 70 72 61 69 74 65 20 65 72 72 6f 72 20 63 6f  opraite error co
1f950 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
1f960 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
1f970 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
1f980 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
1f990 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
1f9a0 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d 20 20  **.** {F15310}  
1f9b0 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
1f9c0 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75  nterrupt|interru
1f9d0 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20  pt] or run-time 
1f9e0 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  error.**        
1f9f0 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67     occurs during
1fa00 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
1fa10 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20  te3_step(S)].** 
1fa20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
1fa30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1fa40 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75  ent] S created u
1fa50 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1fa60 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61    legacy interfa
1fa70 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
1fa80 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  pare()] or.**   
1fa90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1faa0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 74 68  _prepare16()] th
1fab0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
1fac0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
1fad0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
1fae0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c  ITE_ERROR], [SQL
1faf0 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53  ITE_BUSY], or [S
1fb00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
1fb10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
1fb20 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
1fb30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fb40 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
1fb50 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
1fb60 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d 0a 2a  t set {F13770}.*
1fb70 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1fb80 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73  number of values
1fb90 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1fba0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
1fbb0 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t set..**.** INV
1fbc0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1fbd0 46 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61  F13771}  After a
1fbe0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1fbf0 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20  3_step(S)] that 
1fc00 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
1fc10 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
1fc20 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ], the [sqlite3_
1fc30 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72  data_count(S)] r
1fc40 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20  outine.**       
1fc50 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20      will return 
1fc60 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61  the same value a
1fc70 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1fc80 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
1fc90 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e  mn_count(S)] fun
1fca0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ction..**.** {F1
1fcb0 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71  3772}  After [sq
1fcc0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
1fcd0 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20  as returned any 
1fce0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1fcf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
1fd00 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65  QLITE_ROW] or be
1fd10 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
1fd20 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20  ep(S)] has been 
1fd30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61  .**           ca
1fd40 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70 72 65  lled on the [pre
1fd50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1fd60 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
1fd70 20 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65    the first time
1fd80 20 73 69 6e 63 65 20 69 74 20 77 61 73 20 5b 73   since it was [s
1fd90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 7c 70  qlite3_prepare|p
1fda0 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20 20 20  repared].**     
1fdb0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
1fdc0 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d 2c 20  3_reset|reset], 
1fdd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
1fde0 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a 20 20  a_count(S)].**  
1fdf0 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
1fe00 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
1fe10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
1fe20 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
1fe30 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1fe40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fe50 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
1fe60 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d 0a 2a  types {F10265}.*
1fe70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
1fe80 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 46  TE_TEXT.**.** {F
1fe90 31 30 32 36 36 7d 45 76 65 72 79 20 76 61 6c 75  10266}Every valu
1fea0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
1feb0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
1fec0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
1fed0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1fee0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
1fef0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
1ff00 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
1ff10 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
1ff20 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
1ff30 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
1ff40 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
1ff50 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
1ff60 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1ff70 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
1ff80 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
1ff90 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
1ffa0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
1ffb0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
1ffc0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
1ffd0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1ffe0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
1fff0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
20000 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
20010 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
20020 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
20030 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
20040 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
20050 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
20060 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a  QLITE3_TEXT not.
20070 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
20080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20090 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
200a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
200b0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
200c0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
200d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
200e0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
200f0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
20100 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
20110 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
20120 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
20130 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
20140 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
20150 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
20160 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61  3REF: Results Va
20170 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
20180 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a 2a 2a  y {F13800}.**.**
20190 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
201a0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
201b0 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65   set query" inte
201c0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
201d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
201e0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
201f0 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  bout.** a single
20200 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
20210 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72 6f  urrent result ro
20220 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49  w of a query.  I
20230 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65 20  n every.** case 
20240 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
20250 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
20260 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  to the .** [prep
20270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20280 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a  that is being.**
20290 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
202a0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
202b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
202c0 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
202d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
202e0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
202f0 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a  variants) and.**
20300 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
20310 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
20320 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
20330 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
20340 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64  ation .** should
20350 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
20360 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
20370 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
20380 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20  t set.** has an 
20390 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a  index of 0..**.*
203a0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
203b0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75  tement is not cu
203c0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
203d0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
203e0 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63   if the.** the c
203f0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
20400 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
20410 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
20420 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20  ined. .** These 
20430 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
20440 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
20450 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
20460 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
20470 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
20480 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
20490 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
204a0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
204b0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
204c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
204d0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73   has been call s
204e0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
204f0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
20500 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
20510 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
20520 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
20530 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
20540 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
20550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20560 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
20570 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
20580 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
20590 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
205a0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
205b0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
205c0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
205d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
205e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
205f0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
20600 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
20610 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
20620 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
20630 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
20640 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
20650 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
20660 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ned.  .**.** The
20670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20680 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
20690 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
206a0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
206b0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
206c0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
206d0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
206e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
206f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
20700 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
20710 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
20720 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
20730 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
20740 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
20750 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
20760 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
20770 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
20780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
20790 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
207a0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
207b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
207c0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
207d0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
207e0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
207f0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
20800 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20810 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
20820 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
20830 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
20840 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
20850 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
20860 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
20870 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20880 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
20890 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
208a0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
208b0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
208c0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
208d0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
208e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
208f0 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65  es() .** routine
20900 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
20910 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
20920 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
20930 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
20940 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
20950 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
20960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
20970 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
20980 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
20990 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
209a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
209b0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
209c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
209d0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
209e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
209f0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
20a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
20a10 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
20a20 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
20a30 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
20a40 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
20a50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20a60 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
20a70 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
20a80 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
20a90 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
20aa0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
20ab0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
20ac0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
20ad0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
20ae0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
20af0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
20b00 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
20b10 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
20b20 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
20b30 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67  rs..**.** String
20b40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
20b50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
20b60 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
20b70 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
20b80 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
20b90 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
20ba0 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
20bb0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a  ed.  The return.
20bc0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
20bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
20be0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
20bf0 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61 6e  ength blob is an
20c00 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
20c10 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
20c20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
20c30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
20c40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
20c50 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
20c60 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
20c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
20c80 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
20c90 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
20ca0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
20cb0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
20cc0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20  tead of UTF-8.  
20cd0 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
20ce0 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
20cf0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
20d00 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
20d10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
20d20 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
20d30 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
20d40 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
20d50 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
20d60 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
20d70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
20d80 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
20d90 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
20da0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
20db0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
20dc0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
20dd0 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72  to do the conver
20de0 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  sion.** automati
20df0 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
20e00 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
20e10 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
20e20 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ons that.** are 
20e30 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
20e40 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
20e50 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
20e60 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
20e70 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
20e80 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
20e90 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
20ea0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
20eb0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
20ec0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
20ed0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
20ee0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
20ef0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
20f00 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
20f10 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
20f20 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
20f30 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
20f40 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
20f50 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
20f60 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
20f70 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
20f80 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
20f90 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
20fa0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
20fb0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
20fc0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
20fd0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
20fe0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
20ff0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
21000 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
21010 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
21020 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
21030 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
21040 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
21050 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45  me as for INTEGE
21060 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
21070 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
21080 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
21090 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
210a0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
210b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
210c0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
210d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
210e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
210f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
21100 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
21110 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
21120 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
21130 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
21140 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
21150 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
21160 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
21170 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
21180 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
21190 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
211a0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
211b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
211c0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
211d0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
211e0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
211f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
21200 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
21210 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
21220 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
21230 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
21240 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
21250 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
21260 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
21270 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
21280 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
21290 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
212a0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
212b0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
212c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
212d0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
212e0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
212f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
21300 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
21310 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
21320 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
21330 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
21340 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
21350 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20  t has its.** on 
21360 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72  equavalent inter
21370 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
21380 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
21390 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
213a0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
213b0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
213c0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
213d0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
213e0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
213f0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
21400 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
21410 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
21420 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
21430 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
21440 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
21450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
21460 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
21470 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
21480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
21490 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
214a0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  be invalidated. 
214b0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
214c0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
214d0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
214e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
214f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
21500 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
21510 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
21520 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
21530 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
21540 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21550 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  xt() .**        
21560 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c    or sqlite3_col
21570 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
21580 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
21590 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
215a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65  .**          nee
215b0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
215c0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e   the string.</p>
215d0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
215e0 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
215f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
21600 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
21610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
21620 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  6() or.**       
21630 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
21640 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
21650 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
21660 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
21670 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
21680 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c   to UTF-16.</p><
21690 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c  /li>.**.** <li><
216a0 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
216b0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
216c0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
216d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
216e0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
216f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21700 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
21710 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
21720 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
21730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
21740 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  UTF-8.</p></li>.
21750 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
21760 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
21770 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
21780 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
21790 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
217a0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
217b0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
217c0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
217d0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
217e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
217f0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
21800 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
21810 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
21820 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
21830 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
21840 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
21850 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
21860 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
21870 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
21880 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e  etime it is.** n
21890 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
218a0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
218b0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
218c0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20  e invalidated.  
218d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
218e0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
218f0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
21900 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
21910 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
21920 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
21930 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
21940 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  .**  <ul>.**  <l
21950 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
21960 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
21970 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
21980 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
21990 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
219a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
219b0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
219c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
219d0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
219e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
219f0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
21a00 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
21a10 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
21a20 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  **  </ul>.**.** 
21a30 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
21a40 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
21a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21a60 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  ext(), sqlite3_c
21a70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  olumn_blob(),.**
21a80 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
21a90 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
21aa0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
21ab0 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64  esult into the d
21ac0 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74  esired.** format
21ad0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
21ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21af0 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  es() or sqlite3_
21b00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
21b10 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20   to.** find the 
21b20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
21b30 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
21b40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
21b50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
21b60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
21b70 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
21b80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
21b90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
21ba0 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a  .  And do not.**
21bb0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
21bc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
21bd0 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73  t16() with calls
21be0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
21bf0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
21c00 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
21c10 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
21c20 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
21c30 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
21c40 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
21c50 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
21c60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21c70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
21c80 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
21c90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21ca0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
21cb0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
21cc0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
21cd0 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73  ngs.** and blobs
21ce0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
21cf0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
21d00 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
21d10 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
21d20 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
21d30 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
21d40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21d50 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
21d60 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  o .** [sqlite3_f
21d70 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
21d80 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
21d90 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
21da0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
21db0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
21dc0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
21dd0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
21de0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
21df0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
21e00 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
21e10 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
21e20 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
21e30 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
21e40 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
21e50 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
21e60 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
21e70 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
21e80 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
21e90 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
21ea0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21eb0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54  **.** {F13803} T
21ec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
21ed0 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
21ee0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
21ef0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
21f00 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
21f10 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
21f20 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
21f30 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
21f40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21f50 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 62  ment] S into a b
21f60 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74  lob and then ret
21f70 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
21f80 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
21f90 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
21fa0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36  e..**.** {F13806
21fb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
21fc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
21fd0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21fe0 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
21ff0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
22000 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20  tes in the blob 
22010 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
22020 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
22030 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
22040 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
22050 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
22060 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
22070 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
22080 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
22090 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
220a0 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
220b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
220c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
220d0 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ,N)]..**.** {F13
220e0 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
220f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
22100 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
22110 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
22120 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
22130 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
22140 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
22150 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
22160 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
22170 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
22180 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
22190 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
221a0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
221b0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
221c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
221d0 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
221e0 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {F13812} The [s
221f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
22200 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
22210 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
22220 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
22230 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
22240 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
22250 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
22260 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
22270 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22280 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61  t] S into a floa
22290 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
222a0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
222b0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
222c0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
222d0 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68  *.** {F13815} Th
222e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
222f0 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65  n_int(S,N)] inte
22300 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
22310 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
22320 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
22330 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
22340 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
22350 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
22360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22370 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 33 32 2d  nt] S into a 32-
22380 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
22390 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
223a0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
223b0 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  y of that intege
223c0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38  r..**.** {F13818
223d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
223e0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29  olumn_int64(S,N)
223f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
22400 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
22410 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
22420 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
22430 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
22440 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
22450 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
22460 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
22470 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
22480 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
22490 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
224a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
224b0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
224c0 46 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13821} The [sql
224d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
224e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
224f0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
22500 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
22510 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
22520 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
22530 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
22540 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
22550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22560 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
22570 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a  minated UTF-8 .*
22580 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
22590 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
225a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
225b0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
225c0 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13824} The [sqli
225d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
225e0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
225f0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
22600 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
22610 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
22620 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
22630 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
22640 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
22650 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22660 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
22670 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
22680 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
22690 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
226a0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
226b0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
226c0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
226d0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
226e0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
226f0 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  827} The [sqlite
22700 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c  3_column_type(S,
22710 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
22720 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
22730 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
22740 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
22750 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
22760 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
22770 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
22780 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
22790 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
227a0 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
227b0 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c       the Nth col
227c0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
227d0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
227e0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
227f0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
22800 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
22810 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20  .**.** {F13830} 
22820 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
22830 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20  umn_value(S,N)] 
22840 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
22850 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
22860 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
22870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
22880 62 6a 65 63 74 20 74 68 61 74 20 66 6f 72 20 74  bject that for t
22890 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
228a0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
228b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
228c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
228d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
228e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
228f0 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  nt] S..*/.const 
22900 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
22910 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
22920 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
22930 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
22940 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
22950 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
22960 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
22970 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
22980 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22990 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
229a0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
229b0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
229c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
229d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
229e0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
229f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
22a00 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
22a10 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
22a20 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
22a30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22a40 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
22a50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
22a60 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
22a70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
22a80 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
22a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22aa0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
22ab0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
22ac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
22ad0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
22ae0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
22af0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
22b00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22b10 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
22b20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
22b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22b40 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
22b50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
22b60 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a  ject {F13300}.**
22b70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22b80 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
22b90 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
22ba0 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70   delete a .** [p
22bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22bc0 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65  t]. If the state
22bd0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63  ment was.** exec
22be0 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
22bf0 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  y, or not execut
22c00 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20  ed at all, then 
22c10 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
22c20 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65  urned..** If exe
22c30 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
22c40 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
22c50 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  hen an .** [erro
22c60 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
22c70 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
22c80 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
22c90 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75   .**.** This rou
22ca0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
22cb0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
22cc0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
22cd0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
22ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22cf0 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72  nt].  If the vir
22d00 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73  tual machine has
22d10 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74   not .** complet
22d20 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
22d30 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
22d40 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
22d50 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
22d60 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
22d70 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e  or an interrupt.
22d80 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f    (See [sqlite3_
22d90 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a  interrupt()].) .
22da0 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
22db0 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
22dc0 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
22dd0 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
22de0 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64  led,  .** depend
22df0 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
22e00 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
22e10 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  e .** [error cod
22e20 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
22e30 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
22e40 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
22e50 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ANTS:.**.** {F11
22e60 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
22e70 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
22e80 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
22e90 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
22ea0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
22eb0 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
22ec0 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
22ed0 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
22ee0 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
22ef0 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
22f00 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ect..**.** {F113
22f10 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
22f20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
22f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
22f40 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
22f50 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
22f60 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
22f70 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
22f80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
22f90 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22fa0 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
22fb0 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
22fc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
22fd0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
22fe0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
23000 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
23010 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
23020 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13330}.**.** T
23030 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
23040 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
23050 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
23060 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
23070 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
23080 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73  ..** back to its
23090 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
230a0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
230b0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
230c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
230d0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
230e0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
230f0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
23100 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
23110 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
23120 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
23130 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
23140 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
23150 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
23160 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
23170 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
23180 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b  * {F11332} The [
23190 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
231a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
231b0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
231c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
231d0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
231e0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
231f0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
23200 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49  **.** {F11334} I
23210 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
23220 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
23230 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
23240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
23250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23260 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
23270 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
23280 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
23290 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
232a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
232b0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
232c0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
232d0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
232e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
232f0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
23300 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
23310 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68  * {F11336} If th
23320 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
23330 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
23340 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20  tep(S)] for.**  
23350 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
23360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
23370 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
23380 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
23390 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
233a0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
233b0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
233c0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
233d0 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b  * {F11338} The [
233e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
233f0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
23400 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
23410 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
23420 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
23430 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
23440 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61  dings] on [prepa
23450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23460 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23470 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
23480 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
23490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
234a0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
234b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
234c0 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F16100}.** KEYWO
234d0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
234e0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
234f0 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74  } .**.** These t
23500 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
23510 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
23520 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e   as.** "function
23530 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
23540 65 73 22 29 20 61 72 65 20 75 73 65 64 20 74 6f  es") are used to
23550 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
23560 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
23570 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69  .** or to redefi
23580 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ne the behavior 
23590 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
235a0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
235b0 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a  regates.  The.**
235c0 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79   difference only
235d0 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f   between the two
235e0 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
235f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
23600 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
23610 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
23620 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
23630 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
23640 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
23650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23660 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
23670 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  6 for sqlite3_cr
23680 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
23690 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
236a0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
236b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
236c0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f  nection] that ho
236d0 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  lds the.** SQL f
236e0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
236f0 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61 64  gate is to be ad
23700 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65 64  ded or redefined
23710 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  . If a single.**
23720 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
23730 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
23740 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 65  base handle inte
23750 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
23760 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  .** functions or
23770 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73 74   aggregates must
23780 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69   be added indivi
23790 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 64  dually to each d
237a0 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c  atabase.** handl
237b0 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68 65  e with which the
237c0 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a  y will be used..
237d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
237e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
237f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
23800 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
23810 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72   created.** or r
23820 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  edefined..** The
23830 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
23840 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
23850 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
23860 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a  lusive of the .*
23870 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  * zero-terminato
23880 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
23890 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
238a0 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
238b0 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
238c0 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
238d0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
238e0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
238f0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
23900 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51   result in an SQ
23910 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72  LITE_ERROR error
23920 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
23930 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
23940 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
23950 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
23960 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
23970 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
23980 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
23990 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
239a0 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
239b0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
239c0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
239d0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
239e0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
239f0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
23a00 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
23a10 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
23a20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
23a30 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
23a40 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
23a50 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
23a60 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
23a70 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
23a80 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
23a90 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
23aa0 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
23ab0 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
23ac0 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
23ad0 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
23ae0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
23af0 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
23b00 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
23b10 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
23b20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
23b30 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
23b40 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
23b50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
23b60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
23b70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
23b80 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
23b90 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
23ba0 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
23bb0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
23bc0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
23bd0 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
23be0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
23bf0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
23c00 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
23c10 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
23c20 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
23c30 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
23c40 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
23c50 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
23c60 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
23c70 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
23c80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
23c90 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
23ca0 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 65  e what.** text e
23cb0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
23cc0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
23cd0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
23ce0 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41   be.** [SQLITE_A
23cf0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  NY]..**.** The f
23d00 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
23d10 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
23d20 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
23d30 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
23d40 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63  f the function c
23d50 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
23d60 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
23d70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
23d80 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a  _user_data()]..*
23d90 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68  *.** The seventh
23da0 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e  , eighth and nin
23db0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
23dc0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
23dd0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
23de0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
23df0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
23e00 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
23e10 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
23e20 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
23e30 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75   A scalar SQL fu
23e40 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
23e50 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
23e60 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e  n of.** the xFun
23e70 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c  c callback only,
23e80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
23e90 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
23ea0 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a 20  as the xStep.** 
23eb0 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61 6d  and xFinal param
23ec0 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67  eters. An aggreg
23ed0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
23ee0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
23ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
23f00 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  f xStep and xFin
23f10 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75  al and NULL shou
23f20 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  ld be passed for
23f30 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74   xFunc. To delet
23f40 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67  e an.** existing
23f50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
23f60 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
23f70 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68   NULL for all th
23f80 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
23f90 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
23fa0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
23fb0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
23fc0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
23fd0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
23fe0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
23ff0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
24000 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
24010 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
24020 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
24030 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
24040 70 65 72 66 65 72 72 65 64 20 74 65 78 74 20 65  perferred text e
24050 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74  ncodings.  SQLit
24060 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
24070 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
24080 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
24090 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
240a0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
240b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
240c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
240d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
240e0 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
240f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24100 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  n16()] interface
24110 20 62 65 68 61 76 65 73 20 65 78 61 63 74 6c 79   behaves exactly
24120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6b  .**          lik
24130 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
24140 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e  e_function()] in
24150 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65 70   every way excep
24160 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20  t that it.**    
24170 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73        interprets
24180 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61   the zFunctionNa
24190 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73 0a 2a  me argument as.*
241a0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
241b0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
241c0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
241d0 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  der instead of a
241e0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
241f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24200 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
24210 36 31 30 36 7d 20 0a 2a 2f 0a 69 6e 74 20 73 71  6106} .*/.int sq
24220 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24230 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
24240 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
24250 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
24260 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
24270 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
24280 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
24290 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
242a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
242b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
242c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
242d0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
242e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
242f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
24300 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
24310 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
24320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
24330 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
24340 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
24350 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
24360 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
24370 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
24380 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
24390 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
243a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
243b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
243c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
243d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
243e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
243f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
24400 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
24410 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
24420 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
24430 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
24440 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36  Encodings {F1026
24450 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  7}.**.** These c
24460 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
24470 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
24480 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
24490 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
244a0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
244b0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
244c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
244d0 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
244e0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
244f0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
24500 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
24510 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
24520 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
24530 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
24540 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
24550 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
24560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24570 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
24580 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
24590 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
245a0 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
245b0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
245c0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
245d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
245e0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
245f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
24600 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e  bsolete Function
24610 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
24620 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20  nctions are all 
24630 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49  now obsolete.  I
24640 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
24650 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
24660 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
24670 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
24680 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73  we continue to s
24690 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20  upport.** these 
246a0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65  functions.  Howe
246b0 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70  ver, new develop
246c0 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68  ment projects sh
246d0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
246e0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
246f0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
24700 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
24710 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
24720 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
24730 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
24740 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
24750 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f  you want they do
24760 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24770 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
24780 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
24790 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
247a0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
247b0 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
247c0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
247d0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
247e0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
247f0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
24800 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
24810 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69  void);.void sqli
24820 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
24830 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  up(void);.int sq
24840 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
24850 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
24860 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
24870 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
24880 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
24890 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
248a0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
248b0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
248c0 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a  es {F15100}.**.*
248d0 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
248e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
248f0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
24900 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
24910 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
24920 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
24930 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
24940 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
24950 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
24960 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
24970 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
24980 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
24990 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
249a0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
249b0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
249c0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
249d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
249e0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
249f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24a00 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
24a10 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
24a20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
24a30 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
24a40 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
24a50 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
24a60 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
24a70 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
24a80 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
24a90 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
24aa0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
24ab0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
24ac0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
24ad0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
24ae0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
24af0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
24b00 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
24b10 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
24b20 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
24b30 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
24b40 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
24b50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24b60 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
24b70 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
24b80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
24b90 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  lumn_blob | sqli
24ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75  te3_column_* rou
24bb0 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68  tines] except th
24bc0 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  at .** these rou
24bd0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
24be0 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  gle [sqlite3_val
24bf0 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73  ue*] pointer ins
24c00 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  tead.** of an [s
24c10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
24c20 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
24c30 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
24c40 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
24c50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24c60 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
24c70 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20  xtracts a UTF16 
24c80 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
24c90 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
24ca0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
24cb0 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
24cc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
24cd0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
24ce0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24cf0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
24d00 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31  .** extract UTF1
24d10 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
24d20 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
24d30 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
24d40 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
24d50 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
24d60 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
24d70 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
24d80 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
24d90 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
24da0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
24db0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
24dc0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
24dd0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
24de0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
24df0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
24e00 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
24e10 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
24e20 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
24e30 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
24e40 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
24e50 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66  ther.** words if
24e60 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
24e70 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
24e80 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
24e90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
24ea0 76 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e  version is done.
24eb0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
24ec0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
24ed0 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  .  The .** [SQLI
24ee0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
24ef0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
24f00 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
24f10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  ned..**.** Pleas
24f20 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
24f30 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
24f40 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
24f50 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
24f60 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  is returned from
24f70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
24f80 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
24f90 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
24fa0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
24fb0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
24fc0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
24fd0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
24fe0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
24ff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
25000 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
25010 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
25020 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
25030 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
25040 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
25050 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a  ext16()].  .**.*
25060 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25070 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
25080 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
25090 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
250a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
250b0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73 71   supplied the sq
250c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61 72  lite3_value* par
250d0 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20  ameters..** Or, 
250e0 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  if the sqlite3_v
250f0 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20 63  alue* argument c
25100 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  omes from the [s
25110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
25120 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  lue()].** interf
25130 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65 20  ace, then these 
25140 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
25150 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
25160 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a 2a  he same thread.*
25170 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c 69  * that ran [sqli
25180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25190 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 63 6f 6e 73 74  ()]..**.*/.const
251a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
251b0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
251c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
251d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
251e0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
251f0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
25200 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
25210 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
25220 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
25230 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
25240 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
25250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
25260 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
25270 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
25280 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
25290 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
252a0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
252b0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
252c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
252d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
252e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
252f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
25300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25310 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25320 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
25330 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
25340 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
25350 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
25360 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
25370 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
25380 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
25390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
253a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
253b0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
253c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
253d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
253e0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
253f0 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
25400 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a  ext {F16210}.**.
25410 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
25420 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
25430 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
25440 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
25450 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
25460 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
25470 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
25480 74 61 74 65 2e 20 20 0a 2a 2a 20 7b 46 31 36 32  tate.  .** {F162
25490 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 74 69  11} The first ti
254a0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
254b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
254c0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
254d0 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
254e0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
254f0 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c  egate, SQLite al
25500 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f  locates nBytes o
25510 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f  f memory.** zero
25520 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  s that memory, a
25530 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
25540 6e 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 7b  nter to it..** {
25550 46 31 36 32 31 32 7d 20 4f 6e 20 73 65 63 6f 6e  F16212} On secon
25560 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
25570 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
25580 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
25590 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ext().** for the
255a0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
255b0 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20  function index, 
255c0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
255d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 45 4e  is returned. {EN
255e0 44 7d 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  D}.** The implem
255f0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
25600 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
25610 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e 65   use the returne
25620 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75  d buffer to accu
25630 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a  mulate data..**.
25640 2a 2a 20 7b 46 31 36 32 31 33 7d 20 53 51 4c 69  ** {F16213} SQLi
25650 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
25660 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63   frees the alloc
25670 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e  ated buffer when
25680 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
25690 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  * query conclude
256a0 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  s. {END}.**.** T
256b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
256c0 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
256d0 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b  opy of the .** [
256e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
256f0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
25700 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
25710 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
25720 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
25730 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
25740 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
25750 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
25760 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
25770 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
25780 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
25790 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
257a0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
257b0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
257c0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
257d0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
257e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
257f0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
25800 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
25810 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
25820 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
25830 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
25840 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F16240}.**.** {F
25850 31 36 32 34 31 7d 20 54 68 65 20 73 71 6c 69 74  16241} The sqlit
25860 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
25870 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25880 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
25890 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
258a0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
258b0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
258c0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
258d0 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b 73 71  * of the the [sq
258e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
258f0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
25900 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25910 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
25920 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
25930 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
25940 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
25950 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
25960 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ction. {END}.**.
25970 2a 2a 20 7b 55 31 36 32 34 33 7d 20 54 68 69 73  ** {U16243} This
25980 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
25990 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
259a0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
259b0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
259c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
259d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
259e0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
259f0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
25a00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25a10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
25a20 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
25a30 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31  xiliary Data {F1
25a40 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6270}.**.** The 
25a50 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
25a60 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
25a70 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
25a80 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
25a90 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
25aa0 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  -data with argum
25ab0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
25ac0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
25ad0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
25ae0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
25af0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
25b00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
25b10 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
25b20 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
25b30 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
25b40 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
25b50 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20  eta-data may be 
25b60 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
25b70 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
25b80 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
25b90 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
25ba0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
25bb0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
25bc0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
25bd0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
25be0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
25bf0 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
25c00 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61  s.** meta-data a
25c10 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
25c20 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
25c30 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
25c40 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
25c50 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
25c60 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
25c70 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
25c80 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
25c90 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
25ca0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
25cb0 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
25cc0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
25cd0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
25ce0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
25cf0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
25d00 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
25d10 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 31  n..**.** {F16271
25d20 7d 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  }.** The sqlite3
25d30 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
25d40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25d50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25d60 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61  e meta-data.** a
25d70 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
25d80 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
25d90 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
25da0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
25db0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
25dc0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
25dd0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
25de0 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 32 37 32 7d 20  on..** {F16272} 
25df0 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20  If no meta-data 
25e00 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62 65  has been ever be
25e10 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
25e20 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
25e30 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
25e40 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72 65 73  or if the coores
25e50 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
25e60 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68 61   parameter.** ha
25e70 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
25e80 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
25e90 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c 69  s set, then sqli
25ea0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
25eb0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  ).** returns a N
25ec0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
25ed0 2a 2a 20 7b 46 31 36 32 37 35 7d 20 54 68 65 20  ** {F16275} The 
25ee0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25ef0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
25f00 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 2d 64  saves the meta-d
25f10 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
25f20 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
25f30 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
25f40 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68 65 20  ta-data for the 
25f50 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
25f60 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
25f70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
25f80 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 53 75 62 73  tion. {END} Subs
25f90 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
25fa0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
25fb0 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
25fc0 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
25fd0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
25fe0 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
25ff0 2e 20 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 49  . .** {F16277} I
26000 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
26010 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
26020 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
26030 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  tor .** function
26040 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
26050 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
26060 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
26070 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
26080 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20 74 68  eta-data when th
26090 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
260a0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
260b0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
260c0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
260d0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
260e0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
260f0 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44 7d 0a  es first. {END}.
26100 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63  **.** In practic
26110 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20  e, meta-data is 
26120 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
26130 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
26140 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
26150 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
26160 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
26170 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
26180 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
26190 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
261a0 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
261b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
261c0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
261d0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
261e0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
261f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
26200 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
26210 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
26220 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
26230 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
26240 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
26250 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
26260 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
26270 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
26280 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
26290 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
262a0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
262b0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
262c0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b  uctor Behavior {
262d0 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10280}.**.** Th
262e0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
262f0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65  value for the de
26300 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
26310 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
26320 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
26330 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
26340 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
26350 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
26360 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
26370 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
26380 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
26390 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
263a0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
263b0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
263c0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
263d0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
263e0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
263f0 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a  estroyed.  The .
26400 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
26410 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
26420 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
26430 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
26440 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
26450 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
26460 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
26470 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
26480 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
26490 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
264a0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
264b0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
264c0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
264d0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
264e0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
264f0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
26500 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
26510 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
26520 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
26530 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
26540 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
26550 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
26560 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
26570 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
26580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26590 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
265a0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
265b0 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
265c0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
265d0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
265e0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
265f0 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F16400}.**.** 
26600 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
26610 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
26620 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
26630 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
26640 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
26650 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
26660 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
26670 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26680 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
26690 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
266a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
266b0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
266c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
266d0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
266e0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
266f0 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20  ch like the .** 
26700 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
26710 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
26720 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66  d_*] family of f
26730 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a  unctions used.**
26740 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
26750 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
26760 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
26770 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
26780 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  fer to the.** [s
26790 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
267a0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
267b0 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  * documentation]
267c0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
267d0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
267e0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 32 7d 20 54  **.** {F16402} T
267f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26800 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
26810 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
26820 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
26830 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
26840 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
26850 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
26860 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
26870 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
26880 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
26890 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
268a0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
268b0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
268c0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a 2a  rd parameter. .*
268d0 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20 73  * {F16403} The s
268e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
268f0 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 63  roblob() inerfac
26900 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
26910 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
26920 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
26930 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
26940 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
26950 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
26960 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
26970 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
26980 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
26990 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
269a0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 37  r..**.** {F16407
269b0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  } The sqlite3_re
269c0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
269d0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
269e0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
269f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
26a00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26a10 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
26a20 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
26a30 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
26a40 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
26a50 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54 68  *.** {F16409} Th
26a60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26a70 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
26a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26a90 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
26aa0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
26ab0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
26ac0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
26ad0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
26ae0 7b 46 31 36 34 31 31 7d 20 53 51 4c 69 74 65 20  {F16411} SQLite 
26af0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
26b00 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
26b10 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
26b20 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
26b30 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
26b40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
26b50 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
26b60 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
26b70 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 7b 46 31  ror message. {F1
26b80 36 34 31 32 7d 20 53 51 4c 69 74 65 20 69 6e 74  6412} SQLite int
26b90 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
26ba0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
26bb0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
26bc0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
26bd0 61 73 20 55 54 46 38 2e 20 20 7b 46 31 36 34 31  as UTF8.  {F1641
26be0 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  3} SQLite.** int
26bf0 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
26c00 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
26c10 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
26c20 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e 61 74   as UTF16 in nat
26c30 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
26c40 72 2e 20 20 7b 46 31 36 34 31 34 7d 20 49 66 20  r.  {F16414} If 
26c50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
26c60 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
26c70 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
26c80 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
26c90 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
26ca0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
26cb0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
26cc0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
26cd0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
26ce0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
26cf0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
26d00 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 49 66 20  .** {F16415} If 
26d10 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
26d20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
26d30 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
26d40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
26d50 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
26d60 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
26d70 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
26d80 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
26d90 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
26da0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
26db0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
26dc0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
26dd0 2a 2a 20 7b 46 31 36 34 31 37 7d 20 54 68 65 20  ** {F16417} The 
26de0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
26df0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
26e00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
26e10 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
26e20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69 76  make a copy priv
26e30 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
26e40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
26e50 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
26e60 79 20 72 65 74 75 72 6e 2e 20 20 7b 45 4e 44 7d  y return.  {END}
26e70 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
26e80 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
26e90 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
26ea0 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
26eb0 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
26ec0 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
26ed0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d  ..**.** {F16421}
26ee0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26ef0 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
26f00 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
26f10 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77  Lite.** to throw
26f20 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63 61   an error indica
26f30 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
26f40 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
26f50 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72   long.** to repr
26f60 65 73 65 6e 74 2e 20 20 7b 46 31 36 34 32 32 7d  esent.  {F16422}
26f70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26f80 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
26f90 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65 73 20  rface.** causes 
26fa0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
26fb0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69 6e 64  an exception ind
26fc0 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
26fd0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
26fe0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
26ff0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 31 7d 20 54  **.** {F16431} T
27000 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27010 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
27020 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
27030 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
27040 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
27050 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
27060 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
27070 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
27080 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
27090 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
270a0 74 2e 0a 2a 2a 20 7b 46 31 36 34 33 32 7d 20 54  t..** {F16432} T
270b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
270c0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
270d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
270e0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
270f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27100 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27110 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
27120 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
27130 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
27140 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
27150 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ent..**.** {F164
27160 33 37 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  37} The sqlite3_
27170 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
27180 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
27190 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
271a0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
271b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
271c0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
271d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 31 7d 20  .**.** {F16441} 
271e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
271f0 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
27200 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
27210 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  (), .** sqlite3_
27220 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
27230 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
27240 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
27250 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
27260 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
27270 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
27280 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
27290 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
272a0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
272b0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
272c0 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
272d0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
272e0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
272f0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
27300 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
27310 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
27320 65 6c 79 2e 0a 2a 2a 20 7b 46 31 36 34 34 32 7d  ely..** {F16442}
27330 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
27340 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
27350 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
27360 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
27370 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
27380 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
27390 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
273a0 63 65 73 2e 0a 2a 2a 20 7b 46 31 36 34 34 34 7d  ces..** {F16444}
273b0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
273c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
273d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
273e0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
273f0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
27400 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
27410 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
27420 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
27430 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  r .** through th
27440 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
27450 72 61 63 74 65 72 2e 0a 2a 2a 20 7b 46 31 36 34  racter..** {F164
27460 34 37 7d 20 49 66 20 74 68 65 20 33 72 64 20 70  47} If the 3rd p
27470 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
27480 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27490 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
274a0 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
274b0 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
274c0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
274d0 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
274e0 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
274f0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
27500 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
27510 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
27520 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
27530 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
27540 2a 2a 20 7b 46 31 36 34 35 31 7d 20 49 66 20 74  ** {F16451} If t
27550 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
27560 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
27570 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
27580 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
27590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
275a0 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
275b0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
275c0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
275d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
275e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
275f0 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f   the text or blo
27600 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  b result when it
27610 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
27620 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
27630 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 33 7d 20  lt..** {F16453} 
27640 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
27650 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
27660 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
27670 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
27680 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
27690 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
276a0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
276b0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
276c0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73 75  n.** SQLite assu
276d0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
276e0 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74  t or blob result
276f0 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   is constant spa
27700 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20 6e  ce and.** does n
27710 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70 61 63  ot copy the spac
27720 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74  e or call a dest
27730 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68  ructor when it h
27740 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
27750 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
27760 2e 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 49 66  ..** {F16454} If
27770 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
27780 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
27790 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
277a0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
277b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
277c0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
277d0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
277e0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
277f0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
27800 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
27810 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
27820 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
27830 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
27840 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
27850 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
27860 0a 2a 2a 20 7b 46 31 36 34 36 31 7d 20 54 68 65  .** {F16461} The
27870 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27880 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
27890 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
278a0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
278b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
278c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
278d0 20 63 6f 70 79 20 74 68 65 20 5b 73 71 6c 69 74   copy the [sqlit
278e0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
278f0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
27900 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27910 65 72 2e 20 20 7b 46 31 36 34 36 33 7d 20 54 68  er.  {F16463} Th
27920 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
27930 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
27940 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
27950 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
27960 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
27970 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 76 61  that [sqlite3_va
27980 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
27990 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
279a0 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
279b0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
279c0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
279d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
279e0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
279f0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 36 34 39 31  m..**.** {U16491
27a00 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  } These routines
27a10 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
27a20 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
27a30 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a  erent thread .**
27a40 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
27a50 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
27a60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27a70 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
27a80 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 20 5b  ecieved.** the [
27a90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
27aa0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
27ab0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
27ac0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
27ad0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
27ae0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27af0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
27b00 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
27b10 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
27b20 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
27b30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27b40 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
27b50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27b60 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
27b70 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
27b80 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
27b90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27ba0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
27bb0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27bc0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
27bd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27be0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
27bf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
27c00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27c10 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
27c20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27c30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27c40 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
27c50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
27c60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27c70 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
27c80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
27c90 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
27ca0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
27cb0 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
27cc0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
27cd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27ce0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
27cf0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
27d00 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
27d10 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
27d20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
27d30 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
27d40 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
27d50 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
27d60 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
27d70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
27d80 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
27d90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
27da0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
27db0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
27dc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27dd0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
27de0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27df0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
27e00 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
27e10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
27e20 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
27e30 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
27e40 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
27e50 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
27e60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
27e70 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
27e80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27e90 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
27ea0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b  ting Sequences {
27eb0 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F16600}.**.** {F
27ec0 31 36 36 30 31 7d 0a 2a 2a 20 54 68 65 73 65 20  16601}.** These 
27ed0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
27ee0 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
27ef0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
27f00 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s to the.** [sql
27f10 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70  ite3*] handle sp
27f20 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
27f30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a  irst argument. .
27f40 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 32 7d 0a 2a  **.** {F16602}.*
27f50 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
27f60 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
27f70 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
27f80 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
27f90 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
27fa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27fb0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
27fc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
27fd0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
27fe0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
27ff0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
28000 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
28010 36 28 29 2e 20 7b 46 31 36 36 30 33 7d 20 49 6e  6(). {F16603} In
28020 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
28030 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
28040 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
28050 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
28060 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d  ..**.** {F16604}
28070 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
28080 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
28090 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
280a0 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
280b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
280c0 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
280d0 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
280e0 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
280f0 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
28100 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
28110 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
28120 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
28130 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
28140 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
28150 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72  little-endian or
28160 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
28170 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
28180 20 7b 46 31 36 36 30 35 7d 20 54 68 65 0a 2a 2a   {F16605} The.**
28190 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
281a0 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53  might also be [S
281b0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
281c0 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65  NED] to indicate
281d0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75   that.** the rou
281e0 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69  tine expects poi
281f0 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20  nters to 16-bit 
28200 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72  word aligned str
28210 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31 36  ings.** of UTF16
28220 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
28230 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  yte order of the
28240 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
28250 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 37 7d 0a 2a  **.** {F16607}.*
28260 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
28270 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
28280 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
28290 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
282a0 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
282b0 2e 20 7b 46 31 36 36 30 39 7d 20 49 66 20 69 74  . {F16609} If it
282c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
282d0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
282e0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
282f0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
28300 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
28310 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
28320 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 7b 46 31  anymore)..** {F1
28330 36 36 31 31 7d 20 45 61 63 68 20 74 69 6d 65 20  6611} Each time 
28340 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
28350 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  ** supplied func
28360 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
28370 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
28380 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
28390 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  * passed as.** t
283a0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
283b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
283c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
283d0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
283e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
283f0 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74  6() as its first
28400 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
28410 2a 20 7b 46 31 36 36 31 32 7d 0a 2a 2a 20 54 68  * {F16612}.** Th
28420 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
28430 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
28440 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
28450 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
28460 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
28470 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
28480 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
28490 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
284a0 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
284b0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
284c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
284d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
284e0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
284f0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
28500 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
28510 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  } The applicatio
28520 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
28530 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
28540 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
28550 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
28560 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68  ositive if.** th
28570 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
28580 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
28590 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
285a0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
285b0 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65  d.** string. i.e
285c0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
285d0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ING2)..**.** {F1
285e0 36 36 31 35 7d 0a 2a 2a 20 54 68 65 20 73 71 6c  6615}.** The sql
285f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
28600 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
28610 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
28620 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
28630 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74 20  .** excapt that 
28640 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
28650 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
28660 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
28670 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
28680 61 74 69 6f 6e 2e 20 20 7b 46 31 36 36 31 37 7d  ation.  {F16617}
28690 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
286a0 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  is called when t
286b0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a  he collation is.
286c0 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ** destroyed and
286d0 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
286e0 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  y of the fourth 
286f0 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20  parameter void* 
28700 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68  pointer.** of th
28710 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
28720 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e  _collation_v2().
28730 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 20 43 6f  .** {F16618}  Co
28740 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
28750 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74  troyed when.** t
28760 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
28770 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c  en by later call
28780 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
28790 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
287a0 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  tions.** or when
287b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20   the [sqlite3*] 
287c0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
287d0 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
287e0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
287f0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
28800 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
28810 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
28820 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
28830 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
28840 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
28850 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
28860 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
28870 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
28880 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
28890 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
288a0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
288b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
288c0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
288d0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
288e0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
288f0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
28900 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
28910 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
28920 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
28930 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
28940 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
28950 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
28960 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
28970 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
28980 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
28990 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
289a0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
289b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
289c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
289d0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
289e0 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
289f0 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
28a00 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a  ks {F16700}.**.*
28a10 2a 20 7b 46 31 36 37 30 31 7d 0a 2a 2a 20 54 6f  * {F16701}.** To
28a20 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
28a30 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
28a40 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
28a50 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
28a60 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
28a70 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
28a80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
28a90 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
28aa0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74   with the.** dat
28ab0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20  abase handle to 
28ac0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
28ad0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
28ae0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
28af0 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65  ce is.** require
28b00 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32  d..**.** {F16702
28b10 7d 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  }.** If the func
28b20 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
28b30 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
28b40 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
28b50 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
28b60 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
28b70 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
28b80 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
28b90 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
28ba0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
28bb0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31  ed in UTF-8. {F1
28bc0 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
28bd0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
28be0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74  d16() is used, t
28bf0 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20  he names.** are 
28c00 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
28c10 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
28c20 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 7b  ve byte order. {
28c30 46 31 36 37 30 34 7d 20 41 20 63 61 6c 6c 20 74  F16704} A call t
28c40 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63  o either.** func
28c50 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
28c60 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
28c70 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37  ack..**.** {F167
28c80 30 35 7d 20 57 68 65 6e 20 74 68 65 20 63 61 6c  05} When the cal
28c90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
28ca0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
28cb0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
28cc0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
28cd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
28ce0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
28cf0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
28d00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
28d10 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
28d20 2e 20 7b 46 31 36 37 30 36 7d 20 54 68 65 20 73  . {F16706} The s
28d30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
28d40 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
28d50 2a 20 68 61 6e 64 6c 65 2e 20 20 7b 46 31 36 37  * handle.  {F167
28d60 30 37 7d 20 54 68 65 20 74 68 69 72 64 20 61 72  07} The third ar
28d70 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
28d80 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
28d90 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
28da0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
28db0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
28dc0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a  ting the most.**
28dd0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
28de0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
28df0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
28e00 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20  on required..** 
28e10 7b 46 31 36 37 30 38 7d 20 54 68 65 20 66 6f 75  {F16708} The fou
28e20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
28e30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28e40 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
28e50 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
28e60 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
28e70 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
28e80 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
28e90 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
28ea0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
28eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
28ec0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
28ed0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
28ee0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
28ef0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
28f00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
28f10 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  v2()]..*/.int sq
28f20 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
28f30 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
28f40 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
28f50 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
28f60 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
28f70 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
28f80 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
28f90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
28fa0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
28fb0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
28fc0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
28fd0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
28fe0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
28ff0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
29000 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
29010 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
29020 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
29030 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
29040 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
29050 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
29060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
29070 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
29080 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
29090 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
290a0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
290b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
290c0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
290d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
290e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
290f0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
29100 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
29110 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
29120 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
29130 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
29140 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
29150 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
29160 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
29170 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
29180 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
29190 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
291a0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
291b0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
291c0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
291d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
291e0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
291f0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
29200 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
29210 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
29220 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
29230 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
29240 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
29250 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
29260 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
29270 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
29280 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
29290 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
292a0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
292b0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
292c0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
292d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
292e0 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74    Suspend Execut
292f0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
29300 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a  Time {F10530}.**
29310 0a 2a 2a 20 7b 46 31 30 35 33 31 7d 20 54 68 65  .** {F10531} The
29320 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
29330 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75   function.** cau
29340 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
29350 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
29360 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
29370 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
29380 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
29390 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
293a0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
293b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 32 7d 20  .**.** {F10532} 
293c0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
293d0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
293e0 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
293f0 65 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a  equests with .**
29400 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
29410 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
29420 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
29430 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
29440 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  o .** the neares
29450 74 20 73 65 63 6f 6e 64 2e 20 7b 46 31 30 35 33  t second. {F1053
29460 33 7d 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  3} The number of
29470 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
29480 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
29490 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
294a0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
294b0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
294c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35  ned..**.** {F105
294d0 33 34 7d 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  34} SQLite imple
294e0 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
294f0 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
29500 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
29510 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
29520 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
29530 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
29540 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  }.*/.int sqlite3
29550 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
29560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e  .** CAPI3REF:  N
29570 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
29580 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
29590 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33 31  ary Files {F1031
295a0 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0}.**.** If this
295b0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
295c0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
295d0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
295e0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
295f0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
29600 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72 79 29  a.ka. directory)
29610 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
29620 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
29630 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
29640 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
29650 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
29660 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61  .  If this varia
29670 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70  ble.** is NULL p
29680 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
29690 69 74 65 20 64 6f 65 73 20 61 20 73 65 61 72 63  ite does a searc
296a0 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
296b0 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a  iate temporary.*
296c0 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  * file directory
296d0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
296e0 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79  t safe to modify
296f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f   this variable o
29700 6e 63 65 20 61 20 64 61 74 61 62 61 73 65 20 63  nce a database c
29710 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73  onnection.** has
29720 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49   been opened.  I
29730 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
29740 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
29750 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
29760 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
29770 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
29780 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
29790 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
297a0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
297b0 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64  ve been call and
297c0 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
297d0 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f  d thereafter..*/
297e0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
297f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
29800 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
29810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54  .** CAPI3REF:  T
29820 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
29830 65 20 44 61 74 61 62 61 73 65 20 49 73 20 49 6e  e Database Is In
29840 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
29850 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a  e {F12930}.**.**
29860 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
29870 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
29880 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73  terfaces returns
29890 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
298a0 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
298b0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
298c0 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
298d0 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
298e0 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
298f0 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f  tively.   Autoco
29900 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a  mmit mode is on.
29910 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ** by default.  
29920 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
29930 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
29940 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
29950 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  nt..** Autocommi
29960 74 20 6d 6f 64 65 20 69 73 20 72 65 65 6e 61 62  t mode is reenab
29970 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
29980 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
29990 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
299a0 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
299b0 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
299c0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
299d0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
299e0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  ** transactions 
299f0 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
29a00 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
29a10 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
29a20 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d   .** [SQLITE_NOM
29a30 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
29a40 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
29a50 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
29a60 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
29a70 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
29a80 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
29a90 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
29aa0 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
29ab0 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65 20 61   out if SQLite a
29ac0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
29ad0 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
29ae0 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
29af0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
29b00 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
29b10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
29b20 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
29b30 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  931} The [sqlite
29b40 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
29b50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
29b60 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
29b70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
29b80 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
29b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29ba0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
29bb0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a   in autocommit.*
29bc0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c  *          mode,
29bd0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
29be0 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41 75  *.** {F12932} Au
29bf0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
29c00 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
29c10 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41  **.** {F12933} A
29c20 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
29c30 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
29c40 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49  successful [BEGI
29c50 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
29c60 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74  .** {F12934} Aut
29c70 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
29c80 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 63  enabled by a suc
29c90 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d  cessful [COMMIT]
29ca0 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a   or [ROLLBACK].*
29cb0 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
29cc0 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20  ment..** .**.** 
29cd0 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a  LIMITATIONS:.***
29ce0 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 66 20  .** {U12936} If 
29cf0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
29d00 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
29d10 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
29d20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
29d30 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74           connect
29d40 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
29d50 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
29d60 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
29d70 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  rn value.**     
29d80 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65       is undefine
29d90 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
29da0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
29db0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
29dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46 69  ** CAPI3REF:  Fi
29dd0 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
29de0 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
29df0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b  ared Statement {
29e00 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F13120}.**.** {F
29e10 31 33 31 32 31 7d 20 54 68 65 20 73 71 6c 69 74  13121} The sqlit
29e20 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
29e30 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
29e40 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  s the [sqlite3*]
29e50 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
29e60 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b   to which a.** [
29e70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29e80 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20  nt] belongs..** 
29e90 7b 46 31 33 31 32 32 7d 20 74 68 65 20 64 61 74  {F13122} the dat
29ea0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74  abase handle ret
29eb0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
29ec0 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  _db_handle.** is
29ed0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
29ee0 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77  se handle that w
29ef0 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  as.** the first 
29f00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
29f10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29f20 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
29f30 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77  riants.** that w
29f40 61 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  as used to creat
29f50 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
29f60 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
29f70 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
29f80 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
29f90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
29fa0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
29fb0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
29fc0 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
29fd0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
29fe0 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12950}.**.** {F
29ff0 31 32 39 35 31 7d 20 54 68 65 20 73 71 6c 69 74  12951} The sqlit
2a000 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2a010 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2a020 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2a030 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2a040 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2a050 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2a060 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a   is committed..*
2a070 2a 20 7b 46 31 32 39 35 32 7d 20 41 6e 79 20 63  * {F12952} Any c
2a080 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2a090 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2a0a0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2a0b0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2a0c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2a0d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2a0e0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 7b 46  verridden..** {F
2a0f0 31 32 39 35 33 7d 20 54 68 65 20 73 71 6c 69 74  12953} The sqlit
2a100 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2a110 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2a120 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2a130 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
2a140 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2a150 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
2a160 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
2a170 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 41 6e 79  .** {F12954} Any
2a180 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2a190 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2a1a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2a1b0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2a1c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2a1d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2a1e0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2a1f0 7b 46 31 32 39 35 36 7d 20 54 68 65 20 70 41 72  {F12956} The pAr
2a200 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
2a210 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20  ssed through.** 
2a220 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  to the callback.
2a230 20 20 7b 46 31 32 39 35 37 7d 20 49 66 20 74 68    {F12957} If th
2a240 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2a250 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2a260 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73  tion .** returns
2a270 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
2a280 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
2a290 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2a2a0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  ollback..**.** {
2a2b0 46 31 32 39 35 38 7d 20 49 66 20 61 6e 6f 74 68  F12958} If anoth
2a2c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
2a2d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
2a2e0 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
2a2f0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
2a300 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
2a310 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2a320 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 39  d..**.** {F12959
2a330 7d 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20  } Registering a 
2a340 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
2a350 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
2a360 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
2a370 36 31 7d 20 46 6f 72 20 74 68 65 20 70 75 72 70  61} For the purp
2a380 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2a390 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2a3a0 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2a3b0 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20  been .** rolled 
2a3c0 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
2a3d0 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
2a3e0 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
2a3f0 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
2a400 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
2a410 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
2a420 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
2a430 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 7b 46 31 32  o occur..** {F12
2a440 39 36 32 7d 20 54 68 65 20 72 6f 6c 6c 62 61 63  962} The rollbac
2a450 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
2a460 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
2a470 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
2a480 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2a490 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
2a4a0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2a4b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
2a4c0 6f 73 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 36 34  osed..** {F12964
2a4d0 7d 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  } The rollback c
2a4e0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2a4f0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2a500 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f  saction is.** ro
2a510 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
2a520 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  e a commit callb
2a530 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e  ack returned non
2a540 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e  -zero..** <todo>
2a550 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c   Check on this <
2a560 2f 74 6f 64 6f 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a  /todo> {END}.**.
2a570 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65 78 70  ** These are exp
2a580 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
2a590 61 63 65 73 20 61 6e 64 20 61 72 65 20 73 75 62  aces and are sub
2a5a0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a  ject to change..
2a5b0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2a5c0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
2a5d0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
2a5e0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
2a5f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
2a600 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
2a610 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
2a620 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
2a630 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2a640 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
2a650 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2a660 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F12970}.**.** 
2a670 7b 46 31 32 39 37 31 7d 20 54 68 65 20 73 71 6c  {F12971} The sql
2a680 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2a690 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
2a6a0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2a6b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
2a6c0 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
2a6d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
2a6e0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
2a6f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a700 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2a710 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
2a720 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2a730 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2a740 20 7b 46 31 32 39 37 32 7d 20 41 6e 79 20 63 61   {F12972} Any ca
2a750 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2a760 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2a770 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66   this function f
2a780 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  or the same .** 
2a790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a7a0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2a7b0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 34  n..**.** {F12974
2a7c0 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  } The second arg
2a7d0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2a7e0 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
2a7f0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
2a800 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75  n a .** row is u
2a810 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
2a820 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a   or deleted. .**
2a830 20 7b 46 31 32 39 37 36 7d 20 54 68 65 20 66 69   {F12976} The fi
2a840 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2a850 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  the callback is.
2a860 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ** a copy of the
2a870 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2a880 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
2a890 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 7b 46 31  e_hook()..** {F1
2a8a0 32 39 37 37 7d 20 54 68 65 20 73 65 63 6f 6e 64  2977} The second
2a8b0 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72   callback .** ar
2a8c0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
2a8d0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
2a8e0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
2a8f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  ] or [SQLITE_UPD
2a900 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  ATE],.** dependi
2a910 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
2a920 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
2a930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  the callback to 
2a940 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 7b  be invoked..** {
2a950 46 31 32 39 37 38 7d 20 54 68 65 20 74 68 69 72  F12978} The thir
2a960 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68  d and .** fourth
2a970 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2a980 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
2a990 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
2a9a0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
2a9b0 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  .** table name c
2a9c0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
2a9d0 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 7b  fected row..** {
2a9e0 46 31 32 39 37 39 7d 20 54 68 65 20 66 69 6e 61  F12979} The fina
2a9f0 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
2aa00 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20  eter is .** the 
2aa10 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77  rowid of the row
2aa20 2e 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 49 6e  ..** {F12981} In
2aa30 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
2aa40 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
2aa50 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20  the rowid after 
2aa60 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20 74  .** the update t
2aa70 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
2aa80 2a 20 7b 46 31 32 39 38 33 7d 20 54 68 65 20 75  * {F12983} The u
2aa90 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
2aaa0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
2aab0 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
2aac0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
2aad0 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
2aae0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
2aaf0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
2ab00 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 34 7d 20 49  **.** {F12984} I
2ab10 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2ab20 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2ab30 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2ab40 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20  s pArg value.** 
2ab50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46  is returned.  {F
2ab60 31 32 39 38 35 7d 20 4f 74 68 65 72 77 69 73 65  12985} Otherwise
2ab70 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2ab80 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  d..*/.void *sqli
2ab90 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2aba0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2abb0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2abc0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2abd0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2abe0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2abf0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2ac00 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
2ac10 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
2ac20 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20  red Pager Cache 
2ac30 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F10330}.**.** {
2ac40 46 31 30 33 33 31 7d 0a 2a 2a 20 54 68 69 73 20  F10331}.** This 
2ac50 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
2ac60 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
2ac70 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
2ac80 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
2ac90 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
2aca0 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
2acb0 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  een connections 
2acc0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
2acd0 62 61 73 65 2e 0a 2a 2a 20 7b 46 31 30 33 33 32  base..** {F10332
2ace0 7d 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20  }.** Sharing is 
2acf0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
2ad00 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20  rgument is true 
2ad10 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
2ad20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
2ad30 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
2ad40 7b 46 31 30 33 33 33 7d 20 43 61 63 68 65 20 73  {F10333} Cache s
2ad50 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
2ad60 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a  d and disabled.*
2ad70 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  * for an entire 
2ad80 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54  process. {END} T
2ad90 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
2ada0 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
2adb0 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49  sion 3.5.0..** I
2adc0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
2add0 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72   of SQLite, shar
2ade0 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c  ing was.** enabl
2adf0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
2ae00 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
2ae10 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2ae20 20 7b 46 31 30 33 33 34 7d 0a 2a 2a 20 54 68 65   {F10334}.** The
2ae30 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
2ae40 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
2ae50 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
2ae60 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
2ae70 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
2ae80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2ae90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2aea0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2aeb0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 7b  _open16()]..** {
2aec0 46 31 30 33 33 35 7d 20 45 78 69 73 74 69 6e 67  F10335} Existing
2aed0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2aee0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2aef0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2af00 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2af10 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2af20 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2af30 6f 70 65 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  opened. {END}.**
2af40 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
2af50 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
2af60 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
2af70 63 61 63 68 65 2e 20 20 7b 46 31 30 33 33 36 7d  cache.  {F10336}
2af80 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20   When shared.** 
2af90 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
2afa0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
2afb0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
2afc0 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
2afd0 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
2afe0 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
2aff0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
2b000 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  or. {END}.**.** 
2b010 7b 46 31 30 33 33 37 7d 20 54 68 69 73 20 72 6f  {F10337} This ro
2b020 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
2b030 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
2b040 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a  red cache was.**
2b050 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2b060 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  bled successfull
2b070 79 2e 20 20 7b 46 31 30 33 33 38 7d 20 41 6e 20  y.  {F10338} An 
2b080 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20  [error code].** 
2b090 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
2b0a0 72 77 69 73 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  rwise. {END}.**.
2b0b0 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72  ** {F10339} Shar
2b0c0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
2b0d0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
2b0e0 20 7b 45 4e 44 7d 20 42 75 74 20 74 68 69 73 20   {END} But this 
2b0f0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
2b100 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
2b110 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
2b120 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
2b130 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
2b140 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
2b150 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
2b160 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2f  t explicitly..*/
2b170 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
2b180 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
2b190 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2b1a0 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74  PI3REF:  Attempt
2b1b0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2b1c0 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a  mory {F17340}.**
2b1d0 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54 68 65  .** {F17341} The
2b1e0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2b1f0 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
2b200 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a  ace attempts to.
2b210 2a 2a 20 66 72 65 65 20 4e 20 62 79 74 65 73 20  ** free N bytes 
2b220 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
2b230 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
2b240 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2b250 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
2b260 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ns held by the d
2b270 61 74 61 62 61 73 65 20 6c 61 62 72 61 72 79 2e  atabase labrary.
2b280 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
2b290 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20  sed.** to cache 
2b2a0 64 61 74 61 62 61 73 65 20 70 61 67 65 73 20 74  database pages t
2b2b0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2b2c0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2b2d0 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73  ple of.** non-es
2b2e0 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20  sential memory. 
2b2f0 20 7b 46 31 36 33 34 32 7d 20 73 71 6c 69 74 65   {F16342} sqlite
2b300 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2b310 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  () returns.** th
2b320 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2b330 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
2b340 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
2b350 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a   more or less.**
2b360 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
2b370 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69   requested..*/.i
2b380 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
2b390 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
2b3a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b3b0 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74    Impose A Limit
2b3c0 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46   On Heap Size {F
2b3d0 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  17350}.**.** {F1
2b3e0 36 33 35 31 7d 20 54 68 65 20 73 71 6c 69 74 65  6351} The sqlite
2b3f0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2b400 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  t() interface.**
2b410 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22   places a "soft"
2b420 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
2b430 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
2b440 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
2b450 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20  allocated.** by 
2b460 53 51 4c 69 74 65 2e 20 7b 46 31 36 33 35 32 7d  SQLite. {F16352}
2b470 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
2b480 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
2b490 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74  quested .** that
2b4a0 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2b4b0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2b4c0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  t, [sqlite3_rele
2b4d0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
2b4e0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20  .** invoked one 
2b4f0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2b500 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70   free up some sp
2b510 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61  ace before the a
2b520 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
2b530 6d 61 64 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  made. {END}.**.*
2b540 2a 20 7b 46 31 36 33 35 33 7d 20 54 68 65 20 6c  * {F16353} The l
2b550 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2b560 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
2b570 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  f.** [sqlite3_re
2b580 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
2b590 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73  cannot.** free s
2b5a0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2b5b0 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20   to prevent the 
2b5c0 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67  limit from being
2b5d0 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68   exceeded,.** th
2b5e0 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  e memory is allo
2b5f0 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64  cated anyway and
2b600 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65   the current ope
2b610 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e  ration proceeds.
2b620 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 0a  .**.** {F16354}.
2b630 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72  ** A negative or
2b640 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
2b650 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
2b660 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
2b670 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
2b680 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2b690 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
2b6a0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2b6b0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
2b6c0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 7b 46 31 36  hausted..** {F16
2b6d0 33 35 35 7d 20 54 68 65 20 64 65 66 61 75 6c 74  355} The default
2b6e0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73   value for the s
2b6f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2b700 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51  s zero..**.** SQ
2b710 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
2b720 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
2b730 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
2b740 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 7b 46 31 36  limit.  .** {F16
2b750 33 35 36 7d 20 42 75 74 20 69 66 20 74 68 65 20  356} But if the 
2b760 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2b770 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 2c 20  cannot honored, 
2b780 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2b790 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2b7a0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2b7b0 66 69 63 61 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  fication. {END} 
2b7c0 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65   This is why the
2b7d0 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61   limit is .** ca
2b7e0 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
2b7f0 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
2b800 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
2b810 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
2b820 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2b830 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
2b840 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
2b850 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
2b860 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
2b870 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
2b880 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2b890 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
2b8a0 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
2b8b0 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
2b8c0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2b8d0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2b8e0 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
2b8f0 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
2b900 2e 20 7b 46 31 36 33 35 37 7d 20 54 68 65 20 76  . {F16357} The v
2b910 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2b920 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2b930 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2b940 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2b950 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2b960 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2b970 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44  ll threads. {END
2b980 7d 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  }  In.** version
2b990 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
2b9a0 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
2b9b0 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
2b9c0 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
2b9d0 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
2b9e0 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
2b9f0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2ba00 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
2ba10 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72   CAPI3REF:  Extr
2ba20 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
2ba30 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
2ba40 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a   Table {F12850}.
2ba50 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2ba60 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65  ne.** returns me
2ba70 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20  ta-data about a 
2ba80 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2ba90 6f 66 20 61 20 73 70 65 63 69 66 69 63 20 64 61  of a specific da
2baa0 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20  tabase.** table 
2bab0 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2bac0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
2bad0 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73  handle passed as
2bae0 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74   the first funct
2baf0 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ion .** argument
2bb00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75  ..**.** The colu
2bb10 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  mn is identified
2bb20 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20   by the second, 
2bb30 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
2bb40 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a   parameters to .
2bb50 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
2bb60 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
2bb70 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72  ameter is either
2bb80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2bb90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e   database.** (i.
2bba0 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e. "main", "temp
2bbb0 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64  " or an attached
2bbc0 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61   database) conta
2bbd0 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66  ining the specif
2bbe0 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20  ied.** table or 
2bbf0 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e  NULL. If it is N
2bc00 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74  ULL, then all at
2bc10 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2bc20 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a   are searched.**
2bc30 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75   for the table u
2bc40 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
2bc50 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20 64  gorithm as the d
2bc60 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75  atabase engine u
2bc70 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c  ses to .** resol
2bc80 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74  ve unqualified t
2bc90 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e  able references.
2bca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
2bcb0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2bcc0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
2bcd0 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20  unction are the 
2bce0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
2bcf0 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65   .** name of the
2bd00 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c   desired column,
2bd10 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e   respectively. N
2bd20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
2bd30 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d  parameters .** m
2bd40 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
2bd50 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69  * Meta informati
2bd60 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  on is returned b
2bd70 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
2bd80 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
2bd90 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
2bda0 68 65 20 35 74 68 20 61 6e 64 20 73 75 62 73 65  he 5th and subse
2bdb0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
2bdc0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2bdd0 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20  n. Any of these 
2bde0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  .** arguments ma
2bdf0 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  y be NULL, in wh
2be00 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
2be10 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
2be20 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69  nt of meta .** i
2be30 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d  nformation is om
2be40 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70  mitted..**.** <p
2be50 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72  re>.** Parameter
2be60 20 20 20 20 20 4f 75 74 70 75 74 20 54 79 70 65       Output Type
2be70 20 20 20 20 20 20 44 65 73 63 72 69 70 74 69 6f        Descriptio
2be80 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  n.** -----------
2be90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
2bea0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20  --------.**.**  
2beb0 20 35 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e   5th         con
2bec0 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 44 61  st char*      Da
2bed0 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68  ta type.**   6th
2bee0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63           const c
2bef0 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f  har*      Name o
2bf00 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f  f the default co
2bf10 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2bf20 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20   .**   7th      
2bf30 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20     int          
2bf40 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20      True if the 
2bf50 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
2bf60 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2bf70 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20 20 20  .**   8th       
2bf80 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20    int           
2bf90 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63     True if the c
2bfa0 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
2bfb0 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
2bfc0 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20 20 20  .**   9th       
2bfd0 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20    int           
2bfe0 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63     True if the c
2bff0 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43  olumn is AUTOINC
2c000 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e  REMENT.** </pre>
2c010 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  .**.**.** The me
2c020 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
2c030 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
2c040 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2c050 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64  ed for the .** d
2c060 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
2c070 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
2c080 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
2c090 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
2c0a0 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ext .** call to 
2c0b0 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49 20 66  any sqlite API f
2c0c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
2c0d0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2c0e0 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
2c0f0 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61  y a view, then a
2c100 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
2c110 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
2c120 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  e specified colu
2c130 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22  mn is "rowid", "
2c140 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f  oid" or "_rowid_
2c150 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54  " and an .** INT
2c160 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2c170 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e   column has been
2c180 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
2c190 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  ared, then the o
2c1a0 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65  utput .** parame
2c1b0 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72  ters are set for
2c1c0 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20   the explicitly 
2c1d0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e  declared column.
2c1e0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a   If there is no.
2c1f0 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
2c200 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d  clared IPK colum
2c210 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  n, then the outp
2c220 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ut parameters ar
2c230 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c  e set as .** fol
2c240 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
2c250 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
2c260 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
2c270 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
2c280 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
2c290 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
2c2a0 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
2c2b0 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
2c2c0 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
2c2d0 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a  : 0.** </pre>.**
2c2e0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
2c2f0 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f  n may load one o
2c300 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66  r more schemas f
2c310 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c  rom database fil
2c320 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72  es. If an.** err
2c330 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2c340 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f   this process, o
2c350 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74  r if the request
2c360 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  ed table or colu
2c370 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  mn.** cannot be 
2c380 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45  found, an SQLITE
2c390 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2c3a0 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
2c3b0 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
2c3c0 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61 74 61  left in the data
2c3d0 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20  base handle (to 
2c3e0 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
2c3f0 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
2c400 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  g())..**.** This
2c410 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
2c420 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2c430 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2c440 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
2c450 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2c460 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65  UMN_METADATA pre
2c470 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2c480 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
2c490 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
2c4a0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
2c4b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c4d0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
2c4e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c4f0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
2c500 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c510 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
2c520 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
2c530 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
2c540 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
2c550 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
2c560 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
2c570 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
2c580 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
2c590 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
2c5a0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
2c5b0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
2c5c0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
2c5d0 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
2c5e0 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
2c5f0 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
2c600 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
2c610 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
2c620 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2c630 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
2c640 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
2c650 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
2c660 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
2c670 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2c680 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
2c690 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
2c6a0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
2c6b0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2c6c0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
2c6d0 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
2c6e0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2c6f0 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
2c700 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30  Extension {F1260
2c710 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31  0}.**.** {F12601
2c720 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
2c730 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2c740 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74 74 65  nterface.** atte
2c750 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 20  mpts to load an 
2c760 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2c770 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
2c780 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a  ed in the file.*
2c790 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36 30 32  * zFile. {F12602
2c7a0 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  } The entry poin
2c7b0 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46 31 32  t is zProc. {F12
2c7c0 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62  603} zProc may b
2c7d0 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63 68 20  e 0.** in which 
2c7e0 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
2c7f0 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
2c800 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74 6f 20   defaults.** to 
2c810 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69  "sqlite3_extensi
2c820 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20  on_init"..**.** 
2c830 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c  {F12604} The sql
2c840 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
2c850 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
2c860 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  shall.** return 
2c870 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2c880 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
2c890 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
2c8a0 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
2c8b0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 35  g..**.** {F12605
2c8c0 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72  }.** If an error
2c8d0 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72   occurs and pzEr
2c8e0 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74  rMsg is not 0, t
2c8f0 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  hen the.** sqlit
2c900 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2c910 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68  n() interface sh
2c920 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 66  all attempt to f
2c930 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69  ill *pzErrMsg wi
2c940 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73  th .** error mes
2c950 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
2c960 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2c970 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2c980 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
2c990 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69  {END}  The calli
2c9a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ng function shou
2c9b0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
2c9c0 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e  ory.** by callin
2c9d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
2c9e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  )]..**.** {F1260
2c9f0 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20  6}.** Extension 
2ca00 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
2ca10 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
2ca20 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2ca30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
2ca40 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
2ca50 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20  ing this API or 
2ca60 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
2ca70 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
2ca80 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
2ca90 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
2caa0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2cab0 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
2cac0 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
2cad0 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
2cae0 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
2caf0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
2cb00 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
2cb10 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
2cb20 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
2cb30 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
2cb40 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
2cb50 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
2cb60 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
2cb70 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
2cb80 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
2cb90 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
2cba0 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
2cbb0 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
2cbc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e  ** CAPI3REF:  En
2cbd0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2cbe0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
2cbf0 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a 2a 2a  g {F12620}.**.**
2cc00 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70   So as not to op
2cc10 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65  en security hole
2cc20 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69  s in older appli
2cc30 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  cations that are
2cc40 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74  .** unprepared t
2cc50 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65  o deal with exte
2cc60 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61  nsion loading, a
2cc70 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66  nd as a means of
2cc80 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78   disabling.** ex
2cc90 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2cca0 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
2ccb0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
2ccc0 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  L, the following
2ccd0 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f 76 69  .** API is provi
2cce0 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20  ded to turn the 
2ccf0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
2cd00 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61  tension()] mecha
2cd10 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f  nism on and.** o
2cd20 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20 49 74  ff.  {F12622} It
2cd30 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
2cd40 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20 74 69  lt. {END} See ti
2cd50 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a  cket #1863..**.*
2cd60 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c 6c 20  * {F12621} Call 
2cd70 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
2cd80 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2cd90 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77  n() routine.** w
2cda0 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20  ith onoff==1 to 
2cdb0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
2cdc0 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64  oading on.** and
2cdd0 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
2cde0 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69  off==0 to turn i
2cdf0 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
2ce00 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73  . {END}.*/.int s
2ce10 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2ce20 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
2ce30 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
2ce40 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
2ce50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61  I3REF: Make Arra
2ce60 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f  ngements To Auto
2ce70 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41  matically Load A
2ce80 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32  n Extension {F12
2ce90 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  640}.**.** {F126
2cea0 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f  41} This functio
2ceb0 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61  n.** registers a
2cec0 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  n extension entr
2ced0 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 20  y point that is 
2cee0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2cef0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65  voked.** wheneve
2cf00 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
2cf10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2cf20 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  pened using.** [
2cf30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2cf40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2cf50 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
2cf60 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b 45 4e  _open_v2()]. {EN
2cf70 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  D}.**.** This AP
2cf80 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64  I can be invoked
2cf90 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72   at program star
2cfa0 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  tup in order to 
2cfb0 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20  register.** one 
2cfc0 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c  or more statical
2cfd0 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73  ly linked extens
2cfe0 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ions that will b
2cff0 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74  e available.** t
2d000 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61  o all new databa
2d010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a  se connections..
2d020 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d 20 44  **.** {F12642} D
2d030 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
2d040 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
2d050 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
2d060 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70 6c   routine multipl
2d070 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2d080 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
2d090 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
2d0a0 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d 20 54  **.** {F12643} T
2d0b0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
2d0c0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
2d0d0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
2d0e0 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68 61   an array.** tha
2d0f0 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  t is obtained fr
2d100 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c 6f 63  om sqlite_malloc
2d110 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79 6f 75  (). {END} If you
2d120 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65   run a memory le
2d130 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e  ak.** checker on
2d140 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e   your program an
2d150 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c  d it reports a l
2d160 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74  eak because of t
2d170 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68  his.** array, th
2d180 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  en invoke [sqlit
2d190 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
2d1a0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2d1b0 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77 6e 20  .** to shutdown 
2d1c0 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f  to free the memo
2d1d0 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34  ry..**.** {F1264
2d1e0 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74  4} Automatic ext
2d1f0 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63  ensions apply ac
2d200 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73  ross all threads
2d210 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
2d220 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
2d230 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
2d240 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
2d250 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f  hange or.** remo
2d260 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65  val in future re
2d270 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2d280 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d290 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2d2a0 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e  void *xEntryPoin
2d2b0 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t);.../*.** CAPI
2d2c0 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f  3REF: Reset Auto
2d2d0 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20  matic Extension 
2d2e0 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36 30 7d  Loading {F12660}
2d2f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31 7d 20  .**.** {F12661} 
2d300 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2d310 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69  sables all previ
2d320 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
2d330 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 65 78  .** automatic ex
2d340 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20  tensions. {END} 
2d350 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   This.** routine
2d360 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
2d370 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 20  ct of all prior 
2d380 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78  [sqlite3_auto_ex
2d390 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61  tension()].** ca
2d3a0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  lls..**.** {F126
2d3b0 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20 64 69  62} This call di
2d3c0 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  sabled automatic
2d3d0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
2d3e0 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44  ll threads. {END
2d3f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
2d400 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
2d410 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
2d420 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
2d430 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
2d440 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2d450 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
2d460 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
2d470 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2d480 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a  (void);.../*.***
2d490 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
2d4a0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
2d4b0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
2d4c0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
2d4d0 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
2d4e0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
2d4f0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2d500 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
2d510 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
2d520 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
2d530 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
2d540 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
2d550 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
2d560 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
2d570 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
2d580 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
2d590 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
2d5a0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
2d5b0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
2d5c0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2d5d0 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c  anism stablizes,
2d5e0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
2d5f0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
2d600 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
2d610 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
2d620 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
2d630 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
2d640 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
2d650 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
2d660 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
2d670 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
2d680 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2d690 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
2d6a0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2d6b0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2d6c0 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
2d6d0 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
2d6e0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2d6f0 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
2d700 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
2d710 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2d720 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
2d730 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
2d740 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20  .** A module is 
2d750 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75  a class of virtu
2d760 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68  al tables.  Each
2d770 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e   module is defin
2d780 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74  ed.** by an inst
2d790 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c  ance of the foll
2d7a0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e  owing structure.
2d7b0 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65    This structure
2d7c0 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73   consists.** mos
2d7d0 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66  tly of methods f
2d7e0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
2d7f0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
2d800 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
2d810 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
2d820 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
2d830 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
2d840 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d850 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
2d860 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
2d870 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2d880 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
2d890 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
2d8a0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
2d8b0 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
2d8c0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
2d8d0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
2d8e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
2d8f0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
2d900 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
2d910 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
2d920 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
2d930 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
2d940 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d950 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
2d960 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
2d970 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
2d980 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d990 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
2d9a0 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
2d9b0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2d9c0 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
2d9d0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
2d9e0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2d9f0 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
2da00 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
2da10 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2da20 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
2da30 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
2da40 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
2da50 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
2da60 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
2da70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2da80 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
2da90 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
2daa0 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
2dab0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2dac0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
2dad0 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
2dae0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2daf0 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
2db00 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2db10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2db20 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
2db30 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
2db40 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
2db50 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
2db60 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
2db70 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
2db80 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
2db90 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
2dba0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
2dbb0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
2dbc0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2dbd0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2dbe0 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
2dbf0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2dc00 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
2dc10 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2dc20 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
2dc30 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
2dc40 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2dc50 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
2dc60 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2dc70 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
2dc80 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2dc90 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
2dca0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2dcb0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
2dcc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2dcd0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2dce0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
2dcf0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
2dd00 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20  *ppArg);..  int 
2dd10 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
2dd20 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
2dd30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
2dd40 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  );.};../*.** The
2dd50 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2dd60 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
2dd70 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
2dd80 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
2dd90 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
2dda0 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
2ddb0 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
2ddc0 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  om the xBestInde
2ddd0 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  x.** method of a
2dde0 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  n sqlite3_module
2ddf0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
2de00 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
2de10 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
2de20 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
2de30 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
2de40 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
2de50 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
2de60 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
2de70 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
2de80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ..**.** The aCon
2de90 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
2dea0 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
2deb0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
2dec0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a   of the.** form:
2ded0 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63  .**.**         c
2dee0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a  olumn OP expr.**
2def0 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20  .** Where OP is 
2df00 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
2df10 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20  &gt;, or &gt;=. 
2df20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75   .** The particu
2df30 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20  lar operator is 
2df40 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f  stored.** in aCo
2df50 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20  nstraint[].op.  
2df60 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
2df70 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
2df80 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72  d in .** aConstr
2df90 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20  aint[].iColumn. 
2dfa0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75   aConstraint[].u
2dfb0 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
2dfc0 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
2dfd0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
2dfe0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
2dff0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
2e000 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
2e010 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
2e020 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
2e030 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70  ot..**.** The op
2e040 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
2e050 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
2e060 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
2e070 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
2e080 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
2e090 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
2e0a0 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
2e0b0 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
2e0c0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
2e0d0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
2e0e0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
2e0f0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
2e100 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
2e110 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  ..** The aConstr
2e120 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
2e130 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
2e140 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20  clause terms in 
2e150 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66  the correct.** f
2e160 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74  orm that refer t
2e170 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
2e180 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
2e190 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
2e1a0 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** Information 
2e1b0 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
2e1c0 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
2e1d0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
2e1e0 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20  ]..** Each term 
2e1f0 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
2e200 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
2e210 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
2e220 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  use..**.** The x
2e230 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
2e240 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
2e250 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
2e260 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
2e270 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
2e280 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
2e290 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
2e2a0 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
2e2b0 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
2e2c0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
2e2d0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
2e2e0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
2e2f0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
2e300 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
2e310 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
2e320 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
2e330 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
2e340 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
2e350 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
2e360 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
2e370 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
2e380 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
2e390 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
2e3a0 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
2e3b0 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
2e3c0 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
2e3d0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
2e3e0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
2e3f0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46  d passed into xF
2e400 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65  ilter..** sqlite
2e410 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64  3_free() is used
2e420 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
2e430 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  if needToFreeIdx
2e440 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
2e450 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
2e460 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
2e470 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46  t output from xF
2e480 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72  ilter will occur
2e490 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
2e4a0 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
2e4b0 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
2e4c0 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
2e4d0 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
2e4e0 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
2e4f0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
2e500 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
2e510 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
2e520 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
2e530 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
2e540 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
2e550 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
2e560 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
2e570 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
2e580 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
2e590 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
2e5a0 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
2e5b0 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
2e5c0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
2e5d0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
2e5e0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
2e5f0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
2e600 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
2e610 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
2e620 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
2e630 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
2e640 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
2e650 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
2e660 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
2e670 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
2e680 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
2e690 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
2e6a0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
2e6b0 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
2e6c0 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
2e6d0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
2e6e0 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
2e6f0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
2e700 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
2e710 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
2e720 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
2e730 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
2e740 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
2e750 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
2e760 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
2e770 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
2e780 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
2e790 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
2e7a0 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
2e7b0 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
2e7c0 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
2e7d0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
2e7e0 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
2e7f0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
2e800 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
2e810 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
2e820 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
2e830 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
2e840 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
2e850 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
2e860 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
2e870 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
2e880 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
2e890 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
2e8a0 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
2e8b0 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
2e8c0 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
2e8d0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
2e8e0 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
2e8f0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
2e900 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
2e910 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
2e920 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
2e930 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
2e940 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
2e950 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
2e960 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
2e970 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
2e980 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
2e990 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
2e9a0 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
2e9b0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
2e9c0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
2e9d0 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
2e9e0 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
2e9f0 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
2ea00 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
2ea10 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
2ea20 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
2ea30 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
2ea40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ea50 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
2ea60 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2ea70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
2ea80 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
2ea90 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
2eaa0 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
2eab0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
2eac0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
2ead0 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
2eae0 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
2eaf0 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
2eb00 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
2eb10 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
2eb20 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
2eb30 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
2eb40 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
2eb50 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
2eb60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2eb70 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
2eb80 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2eb90 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2eba0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
2ebb0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2ebc0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
2ebd0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
2ebe0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2ebf0 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
2ec00 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2ec10 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
2ec20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
2ec30 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
2ec40 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
2ec50 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  /*.** This routi
2ec60 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
2ec70 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
2ec80 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e  ule name with an
2ec90 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65   SQLite.** conne
2eca0 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e  ction.  Module n
2ecb0 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
2ecc0 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63  istered before c
2ecd0 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76  reating new.** v
2ece0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e  irtual tables on
2ecf0 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
2ed00 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65  before using pre
2ed10 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c  existing virtual
2ed20 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68  .** tables of th
2ed30 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74  e module..*/.int
2ed40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ed50 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
2ed60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2ed70 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
2ed80 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
2ed90 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
2eda0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
2edb0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
2edc0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
2edd0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
2ede0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
2edf0 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
2ee00 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
2ee10 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20  e */.  void *   
2ee20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ee30 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
2ee40 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
2ee50 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
2ee60 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2ee70 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
2ee80 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
2ee90 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68  te_module() meth
2eea0 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63  od above,.** exc
2eeb0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f  ept that it allo
2eec0 77 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ws a destructor 
2eed0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73  function to be s
2eee0 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a  pecified. It is.
2eef0 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70  ** even more exp
2ef00 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74  erimental than t
2ef10 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76  he rest of the v
2ef20 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50  irtual tables AP
2ef30 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  I..*/.int sqlite
2ef40 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
2ef50 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2ef60 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2ef70 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
2ef80 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
2ef90 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
2efa0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2efb0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
2efc0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
2efd0 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
2efe0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c  qlite3_module *,
2eff0 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66      /* Methods f
2f000 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
2f010 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
2f020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f030 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
2f040 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
2f050 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
2f060 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
2f070 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
2f080 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2f090 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 76 65  */.);../*.** Eve
2f0a0 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
2f0b0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
2f0c0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
2f0d0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
2f0e0 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
2f0f0 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  be a particular 
2f100 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
2f110 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75  module.  Each su
2f120 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
2f130 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
2f140 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
2f150 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
2f160 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
2f170 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20   The.** purpose 
2f180 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
2f190 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
2f1a0 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
2f1b0 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a  hat are common.*
2f1c0 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  * to all module 
2f1d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
2f1e0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
2f1f0 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
2f200 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
2f210 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
2f220 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
2f230 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
2f240 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
2f250 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
2f260 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
2f270 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
2f280 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
2f290 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
2f2a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2f2b0 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20  free().** prior 
2f2c0 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
2f2d0 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
2f2e0 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65  rMsg.  After the
2f2f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
2f300 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
2f310 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
2f320 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
2f330 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
2f340 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2f350 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
2f360 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
2f370 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
2f380 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20  ill be zeroed.  
2f390 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c  Note.** that sql
2f3a0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
2f3b0 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  nd sqlite3_free(
2f3c0 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68  ) are used on th
2f3d0 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a  e zErrMsg field.
2f3e0 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c  ** since virtual
2f3f0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d   tables are comm
2f400 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64  only implemented
2f410 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74   in loadable ext
2f420 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a  ensions which.**
2f430 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63   do not have acc
2f440 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50  ess to sqlite3MP
2f450 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74  rintf() or sqlit
2f460 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72  e3Free()..*/.str
2f470 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
2f480 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74   {.  const sqlit
2f490 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
2f4a0 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75  le;  /* The modu
2f4b0 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74  le for this virt
2f4c0 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69  ual table */.  i
2f4d0 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20  nt nRef;        
2f4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2f4f0 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
2f500 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  y */.  char *zEr
2f510 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
2f520 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
2f530 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
2f540 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
2f550 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
2f560 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
2f570 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
2f580 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
2f590 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
2f5a0 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  ./* Every module
2f5b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f5c0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
2f5d0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
2f5e0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
2f5f0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
2f600 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
2f610 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  o the virtual ta
2f620 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64  ble and are used
2f630 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f  .** to loop thro
2f640 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20  ugh the virtual 
2f650 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20  table.  Cursors 
2f660 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
2f670 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d  g the.** xOpen m
2f680 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
2f690 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
2f6a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f6b0 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
2f6c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
2f6d0 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
2f6e0 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
2f6f0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
2f700 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
2f710 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
2f720 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
2f730 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
2f740 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
2f750 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
2f760 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
2f770 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
2f780 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
2f790 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
2f7a0 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
2f7b0 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
2f7c0 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
2f7d0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
2f7e0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
2f7f0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
2f800 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
2f810 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  */.};../*.** The
2f820 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f   xCreate and xCo
2f830 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66  nnect methods of
2f840 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68   a module use th
2f850 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
2f860 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
2f870 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
2f880 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
2f890 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
2f8a0 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
2f8b0 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
2f8c0 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e  implement..*/.in
2f8d0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
2f8e0 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
2f8f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72   const char *zCr
2f900 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a  eateTable);../*.
2f910 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
2f920 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c  s can provide al
2f930 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d  ternative implem
2f940 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e  entations of fun
2f950 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20  ctions.** using 
2f960 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f  the xFindFunctio
2f970 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67  n method.  But g
2f980 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
2f990 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
2f9a0 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
2f9b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
2f9c0 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a  verloaded..**.**
2f9d0 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20   This API makes 
2f9e0 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65  sure a global ve
2f9f0 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74  rsion of a funct
2fa00 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69  ion with a parti
2fa10 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e  cular.** name an
2fa20 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  d number of para
2fa30 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20  meters exists.  
2fa40 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74  If no such funct
2fa50 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65  ion exists.** be
2fa60 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73  fore this API is
2fa70 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66   called, a new f
2fa80 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74  unction is creat
2fa90 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  ed.  The impleme
2faa0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
2fab0 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61  e new function a
2fac0 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20  lways causes an 
2fad0 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20  exception to be 
2fae0 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74  thrown.  So.** t
2faf0 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
2fb00 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20  is not good for 
2fb10 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65  anything by itse
2fb20 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a  lf.  Its only.**
2fb30 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62   purpose is to b
2fb40 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72  e a place-holder
2fb50 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
2fb60 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
2fb70 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74  .** by virtual t
2fb80 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ables..**.** Thi
2fb90 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20  s API should be 
2fba0 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20  considered part 
2fbb0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
2fbc0 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a  able interface,.
2fbd0 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65  ** which is expe
2fbe0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62  rimental and sub
2fbf0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a  ject to change..
2fc00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
2fc10 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
2fc20 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
2fc30 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
2fc40 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
2fc50 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
2fc60 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
2fc70 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
2fc80 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
2fc90 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
2fca0 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
2fcb0 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
2fcc0 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
2fcd0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
2fce0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
2fcf0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
2fd00 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
2fd10 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
2fd20 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
2fd30 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
2fd40 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
2fd50 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
2fd60 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
2fd70 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
2fd80 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2fd90 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
2fda0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
2fdb0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
2fdc0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
2fdd0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
2fde0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
2fdf0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a  this comment..**
2fe00 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
2fe10 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
2fe20 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
2fe30 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
2fe40 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ******.*/../*.**
2fe50 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e   CAPI3REF: A Han
2fe60 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42  dle To An Open B
2fe70 4c 4f 42 20 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a  LOB {F17800}.**.
2fe80 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
2fe90 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2fea0 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2feb0 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20   is used to .** 
2fec0 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f  represent an blo
2fed0 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f  b-handle.  A blo
2fee0 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61  b-handle is crea
2fef0 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
2ff00 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
2ff10 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
2ff20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
2ff30 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
2ff40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
2ff50 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
2ff60 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
2ff70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
2ff80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2ff90 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
2ffa0 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
2ffb0 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
2ffc0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
2ffd0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
2ffe0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
2fff0 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c  ize of the.** bl
30000 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  ob in bytes..*/.
30010 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
30020 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
30030 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
30040 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
30050 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
30060 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37 38  mental I/O {F178
30070 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31  10}.**.** {F1781
30080 31 7d 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  1} This interfac
30090 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64 6c  es opens a handl
300a0 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f  e to the blob lo
300b0 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20  cated.** in row 
300c0 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a 43  iRow,, column zC
300d0 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
300e0 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
300f0 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
30100 20 77 6f 72 64 73 2c 20 20 74 68 65 20 73 61 6d   words,  the sam
30110 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c  e blob that woul
30120 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79  d be selected by
30130 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
30140 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c       SELECT zCol
30150 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61  umn FROM zDb.zTa
30160 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20  ble WHERE rowid 
30170 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65  = iRow;.** </pre
30180 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  > {END}.**.** {F
30190 31 37 38 31 32 7d 20 49 66 20 74 68 65 20 66 6c  17812} If the fl
301a0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
301b0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62   non-zero, the b
301c0 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  lob is opened fo
301d0 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77  r .** read and w
301e0 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20  rite access. If 
301f0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
30200 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66  blob is opened f
30210 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65  or read .** acce
30220 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ss. {END}.**.** 
30230 7b 46 31 37 38 31 33 7d 20 4f 6e 20 73 75 63 63  {F17813} On succ
30240 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
30250 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
30260 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71   the new .** [sq
30270 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
30280 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  b handle] is wri
30290 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  tten to *ppBlob.
302a0 20 0a 2a 2a 20 7b 46 31 37 38 31 34 7d 20 4f 74   .** {F17814} Ot
302b0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
302c0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
302d0 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61  d and .** any va
302e0 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a  lue written to *
302f0 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f  ppBlob should no
30300 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65  t be used by the
30310 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 7b 46 31 37   caller..** {F17
30320 38 31 35 7d 20 54 68 69 73 20 66 75 6e 63 74 69  815} This functi
30330 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61  on sets the data
30340 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f  base-handle erro
30350 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
30360 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
30370 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
30380 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
30390 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
303a0 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 65 20 73 68 6f  .** <todo>We sho
303b0 75 6c 64 20 67 6f 20 74 68 72 6f 75 67 68 20 61  uld go through a
303c0 6e 64 20 6d 61 72 6b 20 61 6c 6c 20 69 6e 74 65  nd mark all inte
303d0 72 66 61 63 65 73 20 74 68 61 74 20 62 65 68 61  rfaces that beha
303e0 76 65 20 74 68 69 73 0a 2a 2a 20 77 61 79 20 77  ve this.** way w
303f0 69 74 68 20 61 20 73 69 6d 69 6c 61 72 20 73 74  ith a similar st
30400 61 74 65 6d 65 6e 74 3c 2f 74 6f 64 6f 3e 0a 2a  atement</todo>.*
30410 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
30420 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
30430 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
30440 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
30450 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
30460 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
30470 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
30480 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
30490 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
304a0 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
304b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
304c0 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f  EF:  Close A BLO
304d0 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 33 30  B Handle {F17830
304e0 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e  }.**.** Close an
304f0 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62   open [sqlite3_b
30500 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
30510 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33  e]..**.** {F1783
30520 31 7d 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  1} Closing a BLO
30530 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
30540 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
30550 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
30560 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
30570 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
30580 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
30590 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
305a0 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
305b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
305c0 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  s in autocommit 
305d0 6d 6f 64 65 2e 0a 2a 2a 20 7b 46 31 37 38 33 32  mode..** {F17832
305e0 7d 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20  } If any writes 
305f0 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65  were made to the
30600 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68   BLOB, they migh
30610 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63  t be held in cac
30620 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20  he.** until the 
30630 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  close operation 
30640 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74  if they will fit
30650 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73 69  . {END}.** Closi
30660 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65  ng the BLOB ofte
30670 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61  n forces the cha
30680 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64  nges.** out to d
30690 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e  isk and so if an
306a0 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63  y I/O errors occ
306b0 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69  ur, they will li
306c0 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74  kely occur.** at
306d0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74   the time when t
306e0 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65  he BLOB is close
306f0 64 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 6e 79  d.  {F17833} Any
30700 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
30710 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f  ur during.** clo
30720 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65  sing are reporte
30730 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  d as a non-zero 
30740 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a  return value..**
30750 0a 2a 2a 20 7b 46 31 37 38 33 39 7d 20 54 68 65  .** {F17839} The
30760 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
30770 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
30780 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
30790 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
307a0 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
307b0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
307c0 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e  ll closed..*/.in
307d0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
307e0 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
307f0 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
30800 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20 54  I3REF:  Return T
30810 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
30820 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 35 7d  en BLOB {F17805}
30830 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 38 30 36 7d 20  .**.** {F16806} 
30840 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
30850 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20  in bytes of the 
30860 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20  blob accessible 
30870 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a  via the open .**
30880 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
30890 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61   blob-handle] pa
308a0 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d  ssed as an argum
308b0 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
308c0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
308d0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
308e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
308f0 20 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d    Read Data From
30900 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
30910 74 61 6c 6c 79 20 7b 46 31 37 38 35 30 7d 0a 2a  tally {F17850}.*
30920 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
30930 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
30940 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
30950 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
30960 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
30970 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c  ndle] into a cal
30980 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66  ler supplied buf
30990 66 65 72 2e 0a 2a 2a 20 7b 46 31 37 38 35 31 7d  fer..** {F17851}
309a0 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
309b0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
309c0 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f   buffer.** z fro
309d0 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  m the open blob,
309e0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
309f0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
30a00 2a 2a 20 7b 46 31 37 38 35 32 7d 20 49 66 20 6f  ** {F17852} If o
30a10 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
30a20 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79 74   less than n byt
30a30 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
30a40 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a  of the blob, .**
30a50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
30a60 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
30a70 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
30a80 20 20 7b 46 31 37 38 35 33 7d 20 49 66 20 6e 20    {F17853} If n 
30a90 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
30aa0 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
30ab0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
30ac0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
30ad0 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  ead..**.** {F178
30ae0 35 34 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  54} On success, 
30af0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
30b00 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65  urned. Otherwise
30b10 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  , an .** [error 
30b20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74  code] or an [ext
30b30 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
30b40 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
30b50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
30b60 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f  ob_read(sqlite3_
30b70 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c  blob *, void *z,
30b80 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
30b90 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
30ba0 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 61  I3REF:  Write Da
30bb0 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49  ta Into A BLOB I
30bc0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31  ncrementally {F1
30bd0 37 38 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7870}.**.** This
30be0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
30bf0 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
30c00 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a  into an open .**
30c10 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
30c20 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72   blob-handle] fr
30c30 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69  om a user suppli
30c40 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 7b 46  ed buffer..** {F
30c50 31 37 38 37 31 7d 20 6e 20 62 79 74 65 73 20 6f  17871} n bytes o
30c60 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
30c70 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65  d from the buffe
30c80 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  r.** pointed to 
30c90 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70  by z into the op
30ca0 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
30cb0 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
30cc0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  set..**.** {F178
30cd0 37 32 7d 20 49 66 20 74 68 65 20 5b 73 71 6c 69  72} If the [sqli
30ce0 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
30cf0 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
30d00 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
30d10 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  ment.** was not 
30d20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69  opened for writi
30d30 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61  ng (the flags pa
30d40 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
30d50 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
30d60 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20  .*** was zero), 
30d70 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
30d80 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45  turns [SQLITE_RE
30d90 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ADONLY]..**.** {
30da0 46 31 37 38 37 33 7d 20 54 68 69 73 20 66 75 6e  F17873} This fun
30db0 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d  ction may only m
30dc0 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e  odify the conten
30dd0 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 3b 20  ts of the blob; 
30de0 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
30df0 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73  sible to increas
30e00 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
30e10 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20  blob using this 
30e20 41 50 49 2e 0a 2a 2a 20 7b 46 31 37 38 37 34 7d  API..** {F17874}
30e30 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73   If offset iOffs
30e40 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
30e50 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  n bytes from the
30e60 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62   end of the blob
30e70 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  , .** [SQLITE_ER
30e80 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
30e90 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
30ea0 77 72 69 74 74 65 6e 2e 20 20 7b 46 31 37 38 37  written.  {F1787
30eb0 35 7d 20 49 66 20 6e 20 69 73 0a 2a 2a 20 6c 65  5} If n is.** le
30ec0 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
30ed0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
30ee0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
30ef0 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
30f00 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 36 7d 20 4f  **.** {F17876} O
30f10 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
30f20 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
30f30 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20  . Otherwise, an 
30f40 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
30f50 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
30f60 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
30f70 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  returned..*/.int
30f80 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72   sqlite3_blob_wr
30f90 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ite(sqlite3_blob
30fa0 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   *, const void *
30fb0 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f  z, int n, int iO
30fc0 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
30fd0 41 50 49 33 52 45 46 3a 20 20 56 69 72 74 75 61  API3REF:  Virtua
30fe0 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62  l File System Ob
30ff0 6a 65 63 74 73 20 7b 46 31 31 32 30 30 7d 0a 2a  jects {F11200}.*
31000 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66  *.** A virtual f
31010 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20  ilesystem (VFS) 
31020 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  is an [sqlite3_v
31030 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68  fs] object.** th
31040 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  at SQLite uses t
31050 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69  o interact.** wi
31060 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  th the underlyin
31070 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
31080 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64 73  em.  Most builds
31090 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
310a0 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
310b0 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
310c0 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
310d0 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
310e0 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
310f0 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
31100 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
31110 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
31120 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
31130 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
31140 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
31150 2a 0a 2a 2a 20 7b 46 31 31 32 30 31 7d 20 54 68  *.** {F11201} Th
31160 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  e sqlite3_vfs_fi
31170 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  nd() interface r
31180 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
31190 20 74 6f 20 0a 2a 2a 20 61 20 56 46 53 20 67 69   to .** a VFS gi
311a0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 7b  ven its name.  {
311b0 46 31 31 32 30 32 7d 20 4e 61 6d 65 73 20 61 72  F11202} Names ar
311c0 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65  e case sensitive
311d0 2e 0a 2a 2a 20 7b 46 31 31 32 30 33 7d 20 4e 61  ..** {F11203} Na
311e0 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
311f0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
31200 72 69 6e 67 73 2e 0a 2a 2a 20 7b 46 31 31 32 30  rings..** {F1120
31210 34 7d 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  4} If there is n
31220 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a  o match, a NULL.
31230 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  ** pointer is re
31240 74 75 72 6e 65 64 2e 20 7b 46 31 31 32 30 35 7d  turned. {F11205}
31250 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20   If zVfsName is 
31260 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
31270 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73  fault .** VFS is
31280 20 72 65 74 75 72 6e 65 64 2e 20 7b 45 4e 44 7d   returned. {END}
31290 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31 30 7d 20  .**.** {F11210} 
312a0 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65  New VFSes are re
312b0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71  gistered with sq
312c0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
312d0 65 72 28 29 2e 0a 2a 2a 20 7b 46 31 31 32 31 31  er()..** {F11211
312e0 7d 20 45 61 63 68 20 6e 65 77 20 56 46 53 20 62  } Each new VFS b
312f0 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75  ecomes the defau
31300 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61  lt VFS if the ma
31310 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73  keDflt flag is s
31320 65 74 2e 0a 2a 2a 20 7b 46 31 31 32 31 32 7d 20  et..** {F11212} 
31330 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e  The same VFS can
31340 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
31350 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
31360 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a  thout injury..**
31370 20 7b 46 31 31 32 31 33 7d 20 54 6f 20 6d 61 6b   {F11213} To mak
31380 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46  e an existing VF
31390 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75  S into the defau
313a0 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72  lt VFS, register
313b0 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74   it again.** wit
313c0 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  h the makeDflt f
313d0 6c 61 67 20 73 65 74 2e 20 7b 55 31 31 32 31 34  lag set. {U11214
313e0 7d 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65  } If two differe
313f0 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68  nt VFSes with th
31400 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61  e.** same name a
31410 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74  re registered, t
31420 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
31430 6e 64 65 66 69 6e 65 64 2e 20 20 7b 55 31 31 32  ndefined.  {U112
31440 31 35 7d 20 49 66 20 61 0a 2a 2a 20 56 46 53 20  15} If a.** VFS 
31450 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
31460 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69  th a name that i
31470 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
31480 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68  ty string,.** th
31490 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
314a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
314b0 20 0a 2a 2a 20 7b 46 31 31 32 32 30 7d 20 55 6e   .** {F11220} Un
314c0 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77  register a VFS w
314d0 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ith the sqlite3_
314e0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
314f0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 7b   interface..** {
31500 46 31 31 32 32 31 7d 20 49 66 20 74 68 65 20 64  F11221} If the d
31510 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
31520 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
31530 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
31540 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
31550 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
31560 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
31570 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
31580 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73  /.sqlite3_vfs *s
31590 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
315a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
315b0 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Name);.int sqlit
315c0 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
315d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
315e0 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74  t makeDflt);.int
315f0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
31600 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
31610 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  vfs*);../*.** CA
31620 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 20  PI3REF: Mutexes 
31630 7b 46 31 37 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17000}.**.** T
31640 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
31650 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
31660 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a  es for thread.**
31670 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   synchronization
31680 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  .  Though they a
31690 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
316a0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
316b0 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
316c0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
316d0 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
316e0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
316f0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
31700 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
31710 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
31720 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
31730 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
31740 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74 68  ations .** of th
31750 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ese mutex routin
31760 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69  es.  An appropri
31770 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ate implementati
31780 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65  on.** is selecte
31790 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
317a0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
317b0 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a    The following.
317c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
317d0 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  ns are available
317e0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63   in the SQLite c
317f0 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ore:.**.** <ul>.
31800 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
31810 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c  _MUTEX_OS2.** <l
31820 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
31830 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69  X_PTHREAD.** <li
31840 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
31850 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _W32.** <li>   S
31860 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
31870 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
31880 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
31890 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61  _NOOP implementa
318a0 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66  tion is a set of
318b0 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74 68   routines .** th
318c0 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
318d0 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
318e0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
318f0 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e 67  se in .** a sing
31900 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  le-threaded appl
31910 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51  ication.  The SQ
31920 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a  LITE_MUTEX_OS2,.
31930 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
31940 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c  PTHREAD, and SQL
31950 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d  ITE_MUTEX_W32 im
31960 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
31970 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65   are appropriate
31980 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f 73 2f 32   for use on os/2
31990 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77 69 6e 64  , unix, and wind
319a0 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 53  ows..** .** If S
319b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
319c0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
319d0 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70  E_MUTEX_APPDEF p
319e0 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d  reprocessor.** m
319f0 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69  acro defined (wi
31a00 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54  th "-DSQLITE_MUT
31a10 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74  EX_APPDEF=1"), t
31a20 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20  hen no mutex.** 
31a30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
31a40 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  s included with 
31a50 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  the library.  Th
31a60 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65 72  e.** mutex inter
31a70 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 64 65  face routines de
31a80 66 69 6e 65 64 20 68 65 72 65 20 62 65 63 6f 6d  fined here becom
31a90 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 72 65  e external.** re
31aa0 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68 65 20  ferences in the 
31ab0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 66  SQLite library f
31ac0 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65 6d 65  or which impleme
31ad0 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  ntations.** must
31ae0 20 62 65 20 70 72 6f 76 69 64 65 64 20 62 79 20   be provided by 
31af0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
31b00 20 20 54 68 69 73 20 66 61 63 69 6c 69 74 79 20    This facility 
31b10 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 70 70  allows an.** app
31b20 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c 69  lication that li
31b30 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69  nks against SQLi
31b40 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20 69 74  te to provide it
31b50 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a 20 69  s own mutex.** i
31b60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
31b70 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
31b80 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 69 74  modify the SQLit
31b90 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e core..**.** {F
31ba0 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74  17011} The sqlit
31bb0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
31bc0 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74   routine allocat
31bd0 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65  es a new.** mute
31be0 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  x and returns a 
31bf0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b  pointer to it. {
31c00 46 31 37 30 31 32 7d 20 49 66 20 69 74 20 72 65  F17012} If it re
31c10 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  turns NULL.** th
31c20 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  at means that a 
31c30 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20  mutex could not 
31c40 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 46  be allocated. {F
31c50 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a  17013} SQLite.**
31c60 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73   will unwind its
31c70 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72   stack and retur
31c80 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 46 31 37  n an error. {F17
31c90 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 65 6e  014} The argumen
31ca0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
31cb0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73  mutex_alloc() is
31cc0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
31cd0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a  teger constants:
31ce0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
31cf0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
31d00 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20  X_FAST.** <li>  
31d10 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
31d20 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  URSIVE.** <li>  
31d30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
31d40 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c  TIC_MASTER.** <l
31d50 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
31d60 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c  _STATIC_MEM.** <
31d70 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
31d80 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a  X_STATIC_MEM2.**
31d90 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
31da0 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a  TEX_STATIC_PRNG.
31db0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
31dc0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
31dd0 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
31de0 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 35 7d 20 54  **.** {F17015} T
31df0 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e  he first two con
31e00 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c  stants cause sql
31e10 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
31e20 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20  () to create.** 
31e30 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68  a new mutex.  Th
31e40 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72  e new mutex is r
31e50 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51  ecursive when SQ
31e60 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
31e70 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20  SIVE.** is used 
31e80 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  but not necessar
31e90 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49  ily so when SQLI
31ea0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73  TE_MUTEX_FAST is
31eb0 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20   used. {END}.** 
31ec0 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  The mutex implem
31ed0 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
31ee0 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61  t need to make a
31ef0 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
31f00 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d  between SQLITE_M
31f10 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61  UTEX_RECURSIVE a
31f20 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
31f30 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a  FAST if it does.
31f40 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20  ** not want to. 
31f50 20 7b 46 31 37 30 31 36 7d 20 42 75 74 20 53 51   {F17016} But SQ
31f60 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72  Lite will only r
31f70 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69  equest a recursi
31f80 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63  ve mutex in.** c
31f90 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65  ases where it re
31fa0 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20  ally needs one. 
31fb0 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73 74   {END} If a fast
31fc0 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65  er non-recursive
31fd0 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
31fe0 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69  entation is avai
31ff0 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73  lable on the hos
32000 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20  t platform, the 
32010 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a  mutex subsystem.
32020 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  ** might return 
32030 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20  such a mutex in 
32040 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49  response to SQLI
32050 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a  TE_MUTEX_FAST..*
32060 2a 0a 2a 2a 20 7b 46 31 37 30 31 37 7d 20 54 68  *.** {F17017} Th
32070 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20  e other allowed 
32080 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71  parameters to sq
32090 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
320a0 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a  c() each return.
320b0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
320c0 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73  a static preexis
320d0 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44  ting mutex. {END
320e0 7d 20 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d  }  Four static m
320f0 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73  utexes are.** us
32100 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  ed by the curren
32110 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  t version of SQL
32120 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72  ite.  Future ver
32130 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
32140 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74  ** may add addit
32150 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74  ional static mut
32160 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75  exes.  Static mu
32170 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e  texes are for in
32180 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
32190 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41   SQLite only.  A
321a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
321b0 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65   use SQLite mute
321c0 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73  xes should.** us
321d0 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d  e only the dynam
321e0 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72  ic mutexes retur
321f0 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55  ned by SQLITE_MU
32200 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53  TEX_FAST or.** S
32210 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
32220 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  RSIVE..**.** {F1
32230 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 20  7018} Note that 
32240 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79  if one of the dy
32250 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61  namic mutex para
32260 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d  meters (SQLITE_M
32270 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20  UTEX_FAST.** or 
32280 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
32290 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20  URSIVE) is used 
322a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74  then sqlite3_mut
322b0 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65  ex_alloc().** re
322c0 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e  turns a differen
322d0 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79  t mutex on every
322e0 20 63 61 6c 6c 2e 20 20 7b 46 31 37 30 33 34 7d   call.  {F17034}
322f0 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 74 61   But for the sta
32300 74 69 63 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79  tic .** mutex ty
32310 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75  pes, the same mu
32320 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20  tex is returned 
32330 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68  on every call th
32340 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61  at has.** the sa
32350 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 20  me type number. 
32360 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  {END}.**.** {F17
32370 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33  019} The sqlite3
32380 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f  _mutex_free() ro
32390 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65  utine deallocate
323a0 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  s a previously.*
323b0 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61  * allocated dyna
323c0 6d 69 63 20 6d 75 74 65 78 2e 20 7b 46 31 37 30  mic mutex. {F170
323d0 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61  20} SQLite is ca
323e0 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63  reful to dealloc
323f0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e  ate every.** dyn
32400 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20  amic mutex that 
32410 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 55  it allocates. {U
32420 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d  17021} The dynam
32430 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20  ic mutexes must 
32440 6e 6f 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73  not be in .** us
32450 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  e when they are 
32460 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 55 31  deallocated. {U1
32470 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67  7022} Attempting
32480 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61   to deallocate a
32490 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
324a0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
324b0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20  fined behavior. 
324c0 7b 46 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20  {F17023} SQLite 
324d0 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65  never deallocate
324e0 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75  s.** a static mu
324f0 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  tex. {END}.**.**
32500 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
32510 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
32520 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
32530 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
32540 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
32550 61 20 6d 75 74 65 78 2e 20 7b 46 31 37 30 32 34  a mutex. {F17024
32560 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  } If another thr
32570 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
32580 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
32590 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
325a0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
325b0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
325c0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
325d0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
325e0 54 45 5f 42 55 53 59 2e 20 7b 46 31 37 30 32 35  TE_BUSY. {F17025
325f0 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  }  The sqlite3_m
32600 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72  utex_try() inter
32610 66 61 63 65 20 72 65 74 75 72 6e 73 20 53 51 4c  face returns SQL
32620 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73  ITE_OK.** upon s
32630 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e  uccessful entry.
32640 20 20 7b 46 31 37 30 32 36 7d 20 4d 75 74 65 78    {F17026} Mutex
32650 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
32660 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
32670 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62  _RECURSIVE can b
32680 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70  e entered multip
32690 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20  le times by the 
326a0 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20  same thread..** 
326b0 7b 46 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68  {F17027} In such
326c0 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d   cases the,.** m
326d0 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69  utex must be exi
326e0 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d  ted an equal num
326f0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66  ber of times bef
32700 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65  ore another thre
32710 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e  ad.** can enter.
32720 20 20 7b 55 31 37 30 32 38 7d 20 49 66 20 74 68    {U17028} If th
32730 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 72  e same thread tr
32740 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79  ies to enter any
32750 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f   other.** kind o
32760 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61  f mutex more tha
32770 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61  n once, the beha
32780 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
32790 64 2e 0a 2a 2a 20 7b 46 31 37 30 32 39 7d 20 53  d..** {F17029} S
327a0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
327b0 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
327c0 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
327d0 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
327e0 78 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  xes. {END}.**.**
327f0 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 65   Some systems (e
32800 78 3a 20 77 69 6e 64 6f 77 73 39 35 29 20 64 6f  x: windows95) do
32810 20 6e 6f 74 20 74 68 65 20 6f 70 65 72 61 74 69   not the operati
32820 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  on implemented b
32830 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  y.** sqlite3_mut
32840 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68  ex_try().  On th
32850 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c  ose systems, sql
32860 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
32870 20 77 69 6c 6c 0a 2a 2a 20 61 6c 77 61 79 73 20   will.** always 
32880 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55  return SQLITE_BU
32890 53 59 2e 20 20 7b 46 31 37 30 33 30 7d 20 54 68  SY.  {F17030} Th
328a0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
328b0 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20  ly ever uses.** 
328c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
328d0 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69  y() as an optimi
328e0 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69  zation so this i
328f0 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68  s acceptable beh
32900 61 76 69 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  avior. {END}.**.
32910 2a 2a 20 7b 46 31 37 30 33 31 7d 20 54 68 65 20  ** {F17031} The 
32920 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
32930 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78  ave() routine ex
32940 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74  its a mutex that
32950 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
32960 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
32970 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20  e same thread.  
32980 7b 55 31 37 30 33 32 7d 20 54 68 65 20 62 65 68  {U17032} The beh
32990 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
329a0 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74  fined if the mut
329b0 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  ex is not curren
329c0 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  tly entered by t
329d0 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68  he.** calling th
329e0 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63  read or is not c
329f0 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74  urrently allocat
32a00 65 64 2e 20 20 7b 46 31 37 30 33 33 7d 20 53 51  ed.  {F17033} SQ
32a10 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76  Lite will.** nev
32a20 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b 45  er do either. {E
32a30 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ND}.**.** See al
32a40 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  so: [sqlite3_mut
32a50 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b  ex_held()] and [
32a60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
32a70 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c  theld()]..*/.sql
32a80 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69  ite3_mutex *sqli
32a90 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
32aa0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
32ab0 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71  e3_mutex_free(sq
32ac0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
32ad0 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
32ae0 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f  x_enter(sqlite3_
32af0 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c  mutex*);.int sql
32b00 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73  ite3_mutex_try(s
32b10 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
32b20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
32b30 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33  ex_leave(sqlite3
32b40 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _mutex*);../*.**
32b50 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
32b60 20 56 65 72 69 66 63 61 74 69 6f 6e 20 52 6f 75   Verifcation Rou
32b70 74 69 6e 65 73 20 7b 46 31 37 30 38 30 7d 0a 2a  tines {F17080}.*
32b80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32b90 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
32ba0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
32bb0 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
32bc0 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
32bd0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
32be0 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
32bf0 6d 65 6e 74 73 2e 20 7b 46 31 37 30 38 31 7d 20  ments. {F17081} 
32c00 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a  The SQLite core.
32c10 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68  ** never uses th
32c20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63  ese routines exc
32c30 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73  ept inside an as
32c40 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69  sert() and appli
32c50 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61  cations.** are a
32c60 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77  dvised to follow
32c70 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65   the lead of the
32c80 20 63 6f 72 65 2e 20 20 7b 46 31 37 30 38 32 7d   core.  {F17082}
32c90 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a   The core only.*
32ca0 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65  * provides imple
32cb0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74  mentations for t
32cc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68  hese routines wh
32cd0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
32ce0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51  d.** with the SQ
32cf0 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e  LITE_DEBUG flag.
32d00 20 20 7b 55 31 37 30 38 37 7d 20 45 78 74 65 72    {U17087} Exter
32d10 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
32d20 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
32d30 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
32d40 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
32d50 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
32d60 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
32d70 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
32d80 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
32d90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30  ned..**.** {F170
32da0 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e  83} These routin
32db0 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  es should return
32dc0 20 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74   true if the mut
32dd0 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75  ex in their argu
32de0 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20  ment.** is held 
32df0 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73  or not held, res
32e00 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68  pectively, by th
32e10 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
32e20 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 58  . {END}.**.** {X
32e30 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c 65  17084} The imple
32e40 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74  mentation is not
32e50 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
32e60 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f  vided versions o
32e70 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69  f these.** routi
32e80 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c  nes that actuall
32e90 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68  y work..** If th
32ea0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32eb0 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64   does not provid
32ec0 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72  e working.** ver
32ed0 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72  sions of these r
32ee0 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75  outines, it shou
32ef0 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76  ld at least prov
32f00 69 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 68 61  ide stubs.** tha
32f10 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
32f20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65  true so that one
32f30 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70   does not get sp
32f40 75 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74  urious.** assert
32f50 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 20 7b 45  ion failures. {E
32f60 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 38  ND}.**.** {F1708
32f70 35 7d 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  5} If the argume
32f80 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  nt to sqlite3_mu
32f90 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20  tex_held() is a 
32fa0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
32fb0 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  n.** the routine
32fc0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31   should return 1
32fd0 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 73 65  .  {END} This se
32fe0 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75  ems counter-intu
32ff0 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63  itive since.** c
33000 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78  learly the mutex
33010 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20   cannot be held 
33020 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  if it does not e
33030 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a  xist.  But the.*
33040 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65  * the reason the
33050 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20   mutex does not 
33060 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65  exist is because
33070 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f   the build is no
33080 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78  t.** using mutex
33090 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e  es.  And we do n
330a0 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65  ot want the asse
330b0 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rt() containing 
330c0 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  the.** call to s
330d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
330e0 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20  d() to fail, so 
330f0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72  a non-zero retur
33100 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72  n is.** the appr
33110 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f  opriate thing to
33120 20 64 6f 2e 20 20 7b 46 31 37 30 38 36 7d 20 54   do.  {F17086} T
33130 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
33140 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20 69  _notheld() .** i
33150 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20  nterface should 
33160 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68  also return 1 wh
33170 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20  en given a NULL 
33180 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  pointer..*/.int 
33190 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
331a0 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
331b0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
331c0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71  mutex_notheld(sq
331d0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
331e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
331f0 4d 75 74 65 78 20 54 79 70 65 73 20 7b 46 31 37  Mutex Types {F17
33200 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30  001}.**.** {F170
33210 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
33220 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20  _mutex_alloc()] 
33230 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20  interface takes 
33240 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
33250 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e  t.** which is on
33260 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
33270 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 20 7b 45  er constants. {E
33280 4e 44 7d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ND}.*/.#define S
33290 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
332a0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
332b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
332c0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20  TEX_RECURSIVE   
332d0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
332e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
332f0 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23  IC_MASTER    2.#
33300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
33310 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20  TEX_STATIC_MEM  
33320 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74       3  /* sqlit
33330 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23  e3_malloc() */.#
33340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
33350 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20  TEX_STATIC_MEM2 
33360 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
33370 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
33380 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  y() */.#define S
33390 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
333a0 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20  IC_PRNG      5  
333b0 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  /* sqlite3_rando
333c0 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  m() */.#define S
333d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
333e0 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20  IC_LRU       6  
333f0 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74  /* lru page list
33400 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
33410 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43  REF: Low-Level C
33420 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61  ontrol Of Databa
33430 73 65 20 46 69 6c 65 73 20 7b 46 31 31 33 30 30  se Files {F11300
33440 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 31 7d  }.**.** {F11301}
33450 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
33460 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
33470 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
33480 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74  direct call to t
33490 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  he.** xFileContr
334a0 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68  ol method for th
334b0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
334c0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73  thods] object as
334d0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
334e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
334f0 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65  tabase identifie
33500 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
33510 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 31 33 30  argument. {F1130
33520 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f  2} The.** name o
33530 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
33540 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  s the name assig
33550 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62  ned to the datab
33560 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61  ase by the.** <a
33570 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61   href="lang_atta
33580 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c  ch.html">ATTACH<
33590 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20  /a> SQL command 
335a0 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a  that opened the.
335b0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 46 31  ** database. {F1
335c0 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c  1303} To control
335d0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
335e0 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65  se file, use the
335f0 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20   name "main".** 
33600 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
33610 72 2e 20 7b 46 31 31 33 30 34 7d 20 54 68 65 20  r. {F11304} The 
33620 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
33630 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
33640 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61  his routine.** a
33650 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74  re passed direct
33660 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ly through to th
33670 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
33680 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  rd parameters of
33690 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  .** the xFileCon
336a0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 46  trol method.  {F
336b0 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 72  11305} The retur
336c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78  n value of the x
336d0 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d  FileControl.** m
336e0 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68  ethod becomes th
336f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
33700 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a  f this routine..
33710 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 36 7d 20 49  **.** {F11306} I
33720 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
33730 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29  ameter (zDbName)
33740 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
33750 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a  the name of any.
33760 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  ** open database
33770 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49   file, then SQLI
33780 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75  TE_ERROR is retu
33790 72 6e 65 64 2e 20 7b 46 31 31 33 30 37 7d 20 54  rned. {F11307} T
337a0 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  his error.** cod
337b0 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65  e is not remembe
337c0 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74  red and will not
337d0 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20   be recalled by 
337e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
337f0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
33800 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 55  e3_errmsg()]. {U
33810 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72  11308} The under
33820 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72  lying xFileContr
33830 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a  ol method might.
33840 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53  ** also return S
33850 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 55  QLITE_ERROR.  {U
33860 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 20  11309} There is 
33870 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e  no way to distin
33880 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a  guish between.**
33890 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44   an incorrect zD
338a0 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c  bName and an SQL
338b0 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e  ITE_ERROR return
338c0 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c   from the underl
338d0 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e  ying.** xFileCon
338e0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e  trol method. {EN
338f0 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D}.**.** See als
33900 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  o: [SQLITE_FCNTL
33910 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69  _LOCKSTATE].*/.i
33920 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  nt sqlite3_file_
33930 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a  control(sqlite3*
33940 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
33950 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76  bName, int op, v
33960 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
33970 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20  PI3REF: Testing 
33980 49 6e 74 65 72 66 61 63 65 20 7b 46 31 31 34 30  Interface {F1140
33990 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
339a0 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
339b0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  l() interface is
339c0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75   used to read ou
339d0 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74  t internal.** st
339e0 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e  ate of SQLite an
339f0 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c  d to inject faul
33a00 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66  ts into SQLite f
33a10 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75  or testing.** pu
33a20 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69 72  rposes.  The fir
33a30 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 6f  st parameter a o
33a40 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68  peration code th
33a50 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
33a60 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61   the number, mea
33a70 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74  ning, and operat
33a80 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65  ion of all subse
33a90 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
33aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
33ab0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f  erface is not fo
33ac0 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61  r use by applica
33ad0 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74  tions.  It exist
33ae0 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20  s solely.** for 
33af0 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f  verifying the co
33b00 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrect operation 
33b10 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
33b20 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e  brary.  Dependin
33b30 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20  g.** on how the 
33b40 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
33b50 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73  s compiled, this
33b60 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
33b70 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a   not exist..**.*
33b80 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
33b90 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63   the operation c
33ba0 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e  odes, their mean
33bb0 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65  ings, the parame
33bc0 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b  ters.** they tak
33bd0 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79  e, and what they
33be0 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a   do are all subj
33bf0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
33c00 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a  thout notice..**
33c10 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20   Unlike most of 
33c20 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20  the SQLite API, 
33c30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
33c40 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
33c50 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f  to.** operate co
33c60 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20  nsistently from 
33c70 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
33c80 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20  he next..*/.int 
33c90 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
33ca0 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e  trol(int op, ...
33cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33cc0 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65  EF: Testing Inte
33cd0 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20  rface Operation 
33ce0 43 6f 64 65 73 20 7b 46 31 31 34 31 30 7d 0a 2a  Codes {F11410}.*
33cf0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
33d00 61 6e 74 73 20 61 72 65 20 74 68 65 20 76 61 6c  ants are the val
33d10 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64  id operation cod
33d20 65 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 65  e parameters use
33d30 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 69 72 73  d.** as the firs
33d40 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  t argument to [s
33d50 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74  qlite3_test_cont
33d60 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  rol()]..**.** Th
33d70 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ese parameters a
33d80 6e 64 20 74 68 65 69 72 20 6d 65 61 6e 73 69 6e  nd their meansin
33d90 67 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f  g are subject to
33da0 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f   change.** witho
33db0 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 68 65 73  ut notice.  Thes
33dc0 65 20 76 61 6c 75 65 73 20 61 72 65 20 66 6f 72  e values are for
33dd0 20 74 65 73 74 69 6e 67 20 70 75 72 70 6f 73 65   testing purpose
33de0 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69  s only..** Appli
33df0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
33e00 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68  ot use any of th
33e10 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ese parameters o
33e20 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  r the.** [sqlite
33e30 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29  3_test_control()
33e40 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
33e50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
33e60 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 43 4f  ESTCTRL_FAULT_CO
33e70 4e 46 49 47 20 20 20 20 20 20 20 20 20 20 20 20  NFIG            
33e80 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
33e90 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54  E_TESTCTRL_FAULT
33ea0 5f 46 41 49 4c 55 52 45 53 20 20 20 20 20 20 20  _FAILURES       
33eb0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
33ec0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41  LITE_TESTCTRL_FA
33ed0 55 4c 54 5f 42 45 4e 49 47 4e 5f 46 41 49 4c 55  ULT_BENIGN_FAILU
33ee0 52 45 53 20 20 20 20 33 0a 23 64 65 66 69 6e 65  RES    3.#define
33ef0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
33f00 5f 46 41 55 4c 54 5f 50 45 4e 44 49 4e 47 20 20  _FAULT_PENDING  
33f10 20 20 20 20 20 20 20 20 20 20 34 0a 0a 0a 0a 0a            4.....
33f20 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20  ./*.** Undo the 
33f30 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 65 72  hack that conver
33f40 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ts floating poin
33f50 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 65 67  t types to integ
33f60 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73  er for.** builds
33f70 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 20 77   on processors w
33f80 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20  ithout floating 
33f90 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a  point support..*
33fa0 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
33fb0 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
33fc0 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f 75 62  INT.# undef doub
33fd0 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  le.#endif..#ifde
33fe0 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20  f __cplusplus.} 
33ff0 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 20 27   /* End of the '
34000 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 6f 63  extern "C"' bloc
34010 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64  k */.#endif.#end
34020 69 66 0a                                         if.