/ Hex Artifact Content
Login

Artifact b953ce955c65c07a024212ff76863a5f98c33c79:


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 33 31 35 20 32 30 30 38 2f  in,v 1.315 2008/
05f0: 30 35 2f 32 30 20 31 38 3a 34 33 3a 33 38 20 64  05/20 18:43:38 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 69  SQLite is a stri
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 20  VERSION_NUMBER  
0d80: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d90: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0da0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0db0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0dc0: 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a  bers {F10020}.**
0dd0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
0de0: 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  e3_version.**.**
0df0: 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20   These features 
0e00: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
0e10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0e20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
0e30: 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  ION].** and [SQL
0e40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0e50: 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20  ER] #defines in 
0e60: 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20  the header, but 
0e70: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  are associated.*
0e80: 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  * with the libra
0e90: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
0ea0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
0eb0: 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d  Cautious program
0ec0: 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e  mers might.** in
0ed0: 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e  clude a check in
0ee0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
0ef0: 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  on to verify tha
0f00: 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  t .** sqlite3_li
0f10: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0f20: 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  ) always returns
0f30: 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 5b   the value .** [
0f40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0f50: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
0f60: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
0f70: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
0f80: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
0f90: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0fa0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
0fb0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0fc0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
0fd0: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
0fe0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
0ff0: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1000: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1010: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1020: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1030: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
1040: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1050: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   DLL..**.** INVA
1060: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1070: 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  10021} The [sqli
1080: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1090: 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61  umber()] interfa
10a0: 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ce returns an in
10b0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
10c0: 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49    equal to [SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
10e0: 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30  R]. .**.** {F100
10f0: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
1100: 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67  _version] string
1110: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
1120: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  ns the text of t
1130: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1140: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
1150: 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b  string. .**.** {
1160: 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c  F10023} The [sql
1170: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1180: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
1190: 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
11a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11b0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11c0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11d0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
11e0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
11f0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1200: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1210: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1220: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1230: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1240: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1260: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1270: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1280: 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d  eadsafe {F10100}
1290: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
12a0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
12b0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
12c0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
12d0: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  the SQLITE_THREA
12e0: 44 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 65  DSAFE C preproce
12f0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72  ssor macro is tr
1300: 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  ue, mutexes.** a
1310: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1320: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1330: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20  afe.  When that 
1340: 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a  macro is false,.
1350: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1360: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1370: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1380: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1390: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
13a0: 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  e from more than
13b0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
13c0: 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d 65  ** There is a me
13d0: 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d  asurable perform
13e0: 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f 72  ance penalty for
13f0: 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   enabling mutexe
1400: 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65  s..** So if spee
1410: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69  d is of utmost i
1420: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61  mportance, it ma
1430: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73  kes sense to dis
1440: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  able.** the mute
1450: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61  xes.  But for ma
1460: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75  ximum safety, mu
1470: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20  texes should be 
1480: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20  enabled..** The 
1490: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
14a0: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
14b0: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
14c0: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
14d0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
14e0: 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20  by a program to 
14f0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1500: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1510: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1520: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1530: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1540: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1550: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1560: 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  he SQLITE_THREAD
1570: 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  SAFE macro..**.*
1580: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1590: 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65  .** {F10101} The
15a0: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
15b0: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  safe()] function
15c0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 6f   returns nonzero
15d0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
15e0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
15f0: 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 74  led with its mut
1600: 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 20  exes enabled or 
1610: 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  zero.**         
1620: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
1630: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1640: 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  exes disabled..*
1650: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  /.int sqlite3_th
1660: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
1670: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1680: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1690: 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32  tion Handle {F12
16a0: 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
16b0: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
16c0: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73  ection} {databas
16d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
16e0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
16f0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
1700: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
1710: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1720: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a  nstance of the.*
1730: 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  * opaque structu
1740: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
1750: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
1760: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
1770: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
1780: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
1790: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
17a0: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
17b0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
17c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
17d0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
17e0: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
17f0: 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20 5b  ructors.** and [
1800: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1810: 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74   is its destruct
1820: 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  or.  There are m
1830: 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66  any other interf
1840: 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73  aces.** (such as
1850: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1860: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
1870: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1880: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
1890: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
18a0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
18b0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
18c0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68 69  e methods on thi
18d0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  s.** object..*/.
18e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
18f0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
1900: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1910: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
1920: 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 7d 0a   Types {F10200}.
1930: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1940: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1950: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1960: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1970: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1980: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1990: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
19a0: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
19b0: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
19c0: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
19d0: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
19e0: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
19f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1a00: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1a10: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1a20: 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a 20 64  ferred type.** d
1a30: 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68 65  efinitions.  The
1a40: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
1a50: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
1a60: 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 75 70  types are.** sup
1a70: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
1a80: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1a90: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  ty only..**.** I
1aa0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1ab0: 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b 73   {F10201} The [s
1ac0: 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64  qlite_int64] and
1ad0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
1ae0: 20 74 79 70 65 73 20 73 70 65 63 69 66 79 20 61   types specify a
1af0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 34 2d  .**          64-
1b00: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1b10: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  er..**.** {F1020
1b20: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 75  2} The [sqlite_u
1b30: 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69  int64] and [sqli
1b40: 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 65  te3_uint64] type
1b50: 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20  s specify.**    
1b60: 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20 75        a 64-bit u
1b70: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
1b80: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1b90: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
1ba0: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
1bb0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
1bc0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1bd0: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
1be0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
1bf0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
1c00: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1c10: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
1c20: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
1c30: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
1c40: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1c50: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
1c60: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1c70: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
1c80: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
1c90: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
1ca0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
1cb0: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
1cc0: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
1cd0: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
1ce0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1cf0: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
1d00: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
1d10: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
1d20: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
1d30: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
1d40: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
1d50: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
1d60: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
1d70: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
1d80: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
1d90: 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  nt.*/.#ifdef SQL
1da0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
1db0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
1dc0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
1dd0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
1de0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
1df0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
1e00: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32   Connection {F12
1e10: 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  010}.**.** This 
1e20: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
1e30: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
1e40: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1e50: 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ct.  .**.** Appl
1e60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1e70: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1e80: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
1e90: 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  l.** [prepared s
1ea0: 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a 2a  tatements] and.*
1eb0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
1ec0: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
1ed0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ll [sqlite3_blob
1ee0: 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61 73   | BLOBs] .** as
1ef0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1f00: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1f10: 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 61  ct prior.** to a
1f20: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
1f30: 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  se the [sqlite3]
1f40: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 3c   object..**.** <
1f50: 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65 6e  todo>What happen
1f60: 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 72 61  s to pending tra
1f70: 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 65 20  nsactions?  Are 
1f80: 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  they.** rolled b
1f90: 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e 65  ack, or abandone
1fa0: 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  d?</todo>.**.** 
1fb0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1fc0: 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20 5b  * {F12011} The [
1fd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1fe0: 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72   interface destr
1ff0: 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d  oys an [sqlite3]
2000: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
2010: 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 79      allocated by
2020: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
2030: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2040: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2060: 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ], or [sqlite3_o
2070: 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  pen_v2()]..**.**
2080: 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b 73   {F12012} The [s
2090: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
20a0: 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73 65  function release
20b0: 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73 65  s all memory use
20c0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
20d0: 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
20e0: 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20 6f  and closes all o
20f0: 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  pen files..**.**
2100: 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68 65   {F12013} If the
2110: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2120: 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  tion contains.**
2130: 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2140: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2150: 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62 65  that have not be
2160: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  en.**          f
2170: 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73 71 6c  inalized by [sql
2180: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2190: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
21a0: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20 20  close()].**     
21b0: 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b 53 51       returns [SQ
21c0: 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 6c  LITE_BUSY] and l
21d0: 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e 65 63  eaves the connec
21e0: 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a  tion open..**.**
21f0: 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69 6e 67   {F12014} Giving
2200: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2210: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2230: 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  -op..**.** LIMIT
2240: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
2250: 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 61 6d  12015} The param
2260: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2270: 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 62  _close()] must b
2280: 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  e an [sqlite3] o
2290: 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20  bject.**        
22a0: 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f    pointer previo
22b0: 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
22c0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
22d0: 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20 20  ()] or the .**  
22e0: 20 20 20 20 20 20 20 20 65 71 75 69 76 61 6c 65          equivale
22f0: 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  nt, or NULL..**.
2300: 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 65 20  ** {U12016} The 
2310: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2320: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d  lite3_close()] m
2330: 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
2340: 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  n previously.** 
2350: 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 64 2e           closed.
2360: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2370: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29  close(sqlite3 *)
2380: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
2390: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
23a0: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
23b0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
23c0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
23d0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
23e0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
23f0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
2400: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
2410: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
2420: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
2430: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
2440: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
2450: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2460: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
2470: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
2480: 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a 2a  rface {F12100}.*
2490: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
24b0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
24c0: 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67  t way of running
24d0: 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
24e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77  SQL statements w
24f0: 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66 20  ithout a lot of 
2500: 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a 20  C code.  The.** 
2510: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
2520: 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  re passed in as 
2530: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2540: 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
2550: 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68 65 20  e3_exec().  The 
2560: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
2570: 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20  valuated one by 
2580: 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69 74  one.** until eit
2590: 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  her an error or 
25a0: 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73 20  an interrupt is 
25b0: 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a 2a  encountered or.*
25c0: 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  * until they are
25d0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
25e0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
25f0: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a 20   an optional.** 
2600: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2610: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2620: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2630: 79 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 0a  y query results.
2640: 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ** produced by t
2650: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2660: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2670: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2680: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2690: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
26a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f  ..**.** The erro
26b0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64  r message passed
26c0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
26d0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
26e0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65  is held.** in me
26f0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2700: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2710: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64  oc()].  To avoid
2720: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a   a memory leak,.
2730: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61  ** the calling a
2740: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
2750: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  d call [sqlite3_
2760: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65  free()] on any e
2770: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2780: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
2790: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
27a0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  er when it has f
27b0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
27c0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27d0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ge..**.** If the
27e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
27f0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
2800: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ter is NULL or a
2810: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a  n empty string.*
2820: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f  * or a string co
2830: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68  ntaining only wh
2840: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d  itespace and com
2850: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 53 51 4c 0a  ments, then SQL.
2860: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  ** statements ar
2870: 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20  e evaluated and 
2880: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
2890: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
28a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
28b0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
28c0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
28d0: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c  terms of.** [sql
28e0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28f0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
2900: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
2910: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
2920: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2930: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  xec() routine do
2940: 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68  es nothing to th
2950: 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20  e database that 
2960: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a  cannot be done.*
2970: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
2980: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2990: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
29a0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
29b0: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lize()]..**.** I
29c0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a  NVARIANTS:.** .*
29d0: 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73 75 63  * {F12101} A suc
29e0: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
29f0: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  on of [sqlite3_e
2a00: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a  xec(D,S,C,A,E)].
2a10: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
2a20: 6c 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f  l evaluate all o
2a30: 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  f the UTF-8 enco
2a40: 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ded, semicolon-s
2a50: 65 70 61 72 61 74 65 64 2c 0a 2a 2a 20 20 20 20  eparated,.**    
2a60: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
2a70: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
2a80: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
2a90: 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 65 0a  ng S within the.
2aa0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
2ab0: 65 78 74 20 6f 66 20 74 68 65 20 44 20 5b 64 61  ext of the D [da
2ac0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ad0: 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30  n]..**.** {F1210
2ae0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  2} If the S para
2af0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2b00: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
2b10: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
2b20: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2b30: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69  actions of the i
2b40: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
2b50: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66  e the same as if
2b60: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2b70: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 68 65   S parameter whe
2b80: 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  re an empty stri
2b90: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30  ng..**.** {F1210
2ba0: 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  4} The return va
2bb0: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
2bc0: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65  exec()] shall be
2bd0: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6c   SQLITE_OK if al
2be0: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  l.**          SQ
2bf0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 6e  L statements run
2c00: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e   successfully an
2c10: 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  d to completion.
2c20: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35 7d 20  .**.** {F12105} 
2c30: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
2c40: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
2c50: 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e  c()] shall be an
2c60: 20 61 70 70 72 6f 70 72 69 61 74 65 20 0a 2a 2a   appropriate .**
2c70: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65            non-ze
2c80: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
2c90: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65  if any SQL state
2ca0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  ment fails..**.*
2cb0: 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20 6f 6e  * {F12107} If on
2cc0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2cd0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2ce0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
2cf0: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
2d00: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65         return re
2d10: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
2d20: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
2d30: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a  ot NULL, then.**
2d40: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
2d50: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2d60: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2d70: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73   3rd parameter s
2d80: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
2d90: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65      invoked once
2da0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
2db0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
2dc0: 46 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63  F12110} If the c
2dd0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
2de0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  a non-zero value
2df0: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
2e00: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
2e10: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 65 64     shall aborted
2e20: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2e30: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74  nt it is current
2e40: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a  ly evaluating,.*
2e50: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20  *          skip 
2e60: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
2e70: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  QL statements, a
2e80: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
2e90: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
2ea0: 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71  {F12113} The [sq
2eb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
2ec0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73  utine shall pass
2ed0: 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65 74   its 4th paramet
2ee0: 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20  er through.**   
2ef0: 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31 73         as the 1s
2f00: 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  t parameter of t
2f10: 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
2f20: 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65 20  ** {F12116} The 
2f30: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2f40: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68   routine sets th
2f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2f60: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
2f70: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
2f80: 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
2f90: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 63  columns in the c
2fa0: 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a  urrent row of.**
2fb0: 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
2fc0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39 7d  ..**.** {F12119}
2fd0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
2fe0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65  ec()] routine se
2ff0: 74 73 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  ts the 3rd param
3000: 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a 2a 20  eter of its .** 
3010: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
3020: 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79  k to be an array
3030: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3040: 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20  strings holding 
3050: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
3060: 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20  values for each 
3070: 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
3080: 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65 74  rrent result set
3090: 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20 20   row as.**      
30a0: 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f      obtained fro
30b0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
30c0: 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
30d0: 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b 73   {F12122} The [s
30e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
30f0: 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65 20  outine sets the 
3100: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  4th parameter of
3110: 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
3120: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
3130: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3140: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3150: 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20  holding the.**  
3160: 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66          names of
3170: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
3180: 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as obtained from
3190: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31a0: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
31b0: 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68 65 20  {F12125} If the 
31c0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
31d0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
31e0: 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a  ] is NULL then.*
31f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3200: 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65 76 65  te3_exec()] neve
3210: 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c 6c  r invokes a call
3220: 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72 79  back.  All query
3230: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
3240: 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e 74 6c  ults are silentl
3250: 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a  y discarded..**.
3260: 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20 61  ** {F12131} If a
3270: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
3280: 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20  hile parsing or 
3290: 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f  evaluating any o
32a0: 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20  f the SQL.**    
32b0: 20 20 20 20 20 20 68 61 6e 64 65 64 20 69 6e 20        handed in 
32c0: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20  the S parameter 
32d0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
32e0: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64  (D,S,C,A,E)] and
32f0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
3300: 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20  the E parameter 
3310: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3320: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
3330: 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a  )] shall store.*
3340: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45  *          in *E
3350: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
3360: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72  error message wr
3370: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3380: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20  y obtained.**   
3390: 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c         from [sql
33a0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
33b0: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20 54  **.** {F12134} T
33c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
33d0: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75  (D,S,C,A,E)] rou
33e0: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74  tine shall set t
33f0: 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  he value of.**  
3400: 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55          *E to NU
3410: 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e  LL if E is not N
3420: 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72  ULL and there ar
3430: 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a  e no errors..**.
3440: 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65 20  ** {F12137} The 
3450: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3460: 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69  S,C,A,E)] functi
3470: 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65  on shall set the
3480: 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
3490: 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73 73          and mess
34a0: 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20 76  age accessible v
34b0: 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
34c0: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ode()],.**      
34d0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
34e0: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
34f0: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3500: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 38 7d  ..**.** {F12138}
3510: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65   If the S parame
3520: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3530: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3540: 20 69 73 20 61 20 6e 75 6c 6c 20 6f 72 20 65 6d   is a null or em
3550: 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pty.**          
3560: 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69  string or contai
3570: 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72  ns nothing other
3580: 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65   than whitespace
3590: 2c 20 63 6f 6d 6d 65 6e 74 73 2c 20 61 6e 64 2f  , comments, and/
35a0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
35b0: 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20  emicolons, then 
35c0: 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69  results of [sqli
35d0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  te3_errcode()],.
35e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
35f0: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
3600: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
3610: 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
3620: 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74       shall reset
3630: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20   to indicate no 
3640: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49  errors..**.** LI
3650: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
3660: 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66 69   {U12141} The fi
3670: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
3680: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3690: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c  ] must be an val
36a0: 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20  id and open.**  
36b0: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
36c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
36d0: 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54 68  *.** {U12142} Th
36e0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36f0: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62  ction must not b
3700: 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a  e closed while.*
3710: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3720: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72  te3_exec()] is r
3730: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20 7b  unning..** .** {
3740: 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c  U12143} The call
3750: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
3760: 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33  uld use [sqlite3
3770: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65  _free()] to free
3780: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
3790: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72   memory that *er
37a0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69  rmsg is left poi
37b0: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68  nting at once th
37c0: 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
37d0: 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e      message is n
37e0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
37f0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d 20  .**.** {U12145} 
3800: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  The SQL statemen
3810: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e  t text in the 2n
3820: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
3830: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3840: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  **          must
3850: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
3860: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
3870: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3880: 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
3890: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
38a0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
38b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38c0: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
38d0: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
38e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
38f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3900: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
3910: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64  L to be evaluted
3920: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
3930: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
3940: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
3950: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
3960: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
3970: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
39a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
39b0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
39c0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
39f0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
3a00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3a10: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  F: Result Codes 
3a20: 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57  {F10210}.** KEYW
3a30: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3a40: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3a50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ror codes}.**.**
3a60: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
3a70: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
3a80: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
3a90: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
3aa0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
3ab0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
3ac0: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
3ad0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
3ae0: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
3af0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
3b00: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3b10: 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  odes].*/.#define
3b20: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
3b30: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
3b40: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
3b50: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
3b60: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
3b80: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
3b90: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
3ba0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
3bb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3bc0: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
3bd0: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
3be0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
3bf0: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
3c00: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
3c10: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
3c20: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
3c30: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
3c40: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
3c50: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
3c60: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
3c70: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
3c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3c90: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
3ca0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3cb0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
3cc0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3cd0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
3ce0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
3cf0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
3d00: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3d10: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
3d20: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
3d30: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
3d40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3d50: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
3d60: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
3d70: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
3d80: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
3da0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
3db0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
3dc0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
3dd0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
3de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3df0: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
3e00: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
3e10: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
3e20: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
3e30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
3e40: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
3e50: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
3e60: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
3e70: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3e80: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
3e90: 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   12   /* NOT USE
3ea0: 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f  D. Table or reco
3eb0: 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a  rd not found */.
3ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
3ed0: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
3ee0: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
3ef0: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
3f00: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
3f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
3f20: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
3f30: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
3f40: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
3f50: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
3f60: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
3f70: 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53    15   /* NOT US
3f80: 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63  ED. Database loc
3f90: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
3fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fb0: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
3fc0: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
3fd0: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
3fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
3ff0: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
4000: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4010: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4030: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4040: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
4050: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
4060: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
4070: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
4080: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
4090: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
40a0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
40b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
40c0: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
40d0: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
40e0: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
40f0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4100: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4110: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4120: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4130: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4140: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
4150: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
4160: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
4170: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4180: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
4190: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
41a0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
41b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
41c0: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
41d0: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
41e0: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
41f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4200: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
4210: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
4220: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4230: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
4240: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4250: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
4260: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
4270: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
4280: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42a0: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
42b0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
42c0: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
42d0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
42e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
42f0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4300: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4310: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4320: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4330: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4340: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4350: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4360: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32  ult Codes {F1022
4370: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
4380: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4390: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
43a0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
43b0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
43c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
43d0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
43e0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
43f0: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4400: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4410: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4420: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4430: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4440: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4450: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4460: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
4470: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4480: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
4490: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
44a0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
44b0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
44c0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
44d0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
44e0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
44f0: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4500: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4510: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4520: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4530: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4540: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4550: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4560: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4570: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4580: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4590: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
45a0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
45b0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
45c0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
45d0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
45e0: 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ** for each data
45f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4600: 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
4610: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4620: 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41  lt_codes()].** A
4630: 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20  PI..** .** Some 
4640: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
4650: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4660: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
4670: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
4680: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
4690: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
46a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
46b0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
46c0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
46d0: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
46e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
46f0: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
4700: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
4710: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
4720: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
4730: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4740: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
4750: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
4760: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
4770: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
4780: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
4790: 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 49  y zero..** .** I
47a0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
47b0: 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20 73 79   {F10223} The sy
47c0: 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20  mbolic name for 
47d0: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  an extended resu
47e0: 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63  lt code always c
47f0: 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
4800: 20 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72      a related pr
4810: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4820: 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a  e as a prefix..*
4830: 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20 50 72  *.** {F10224} Pr
4840: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4850: 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20  e names contain 
4860: 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61  a single "_" cha
4870: 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  racter..**.** {F
4880: 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20  10225} Extended 
4890: 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65  result code name
48a0: 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  s contain two or
48b0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
48c0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ters..**.** {F10
48d0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
48e0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
48f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4900: 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  e contains the.*
4910: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72  *          numer
4920: 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20  ic value of its 
4930: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72  corresponding pr
4940: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4950: 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e in.**         
4960: 20 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69   its least signi
4970: 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a  ficant 8 bits..*
4980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4990: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
49a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
49b0: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
49c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
49d0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
49e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
49f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
4a00: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
4a10: 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  TE         (SQLI
4a20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4a30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4a40: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4a50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4a60: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4a80: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4a90: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4aa0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
4ab0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
4ac0: 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c  UNCATE      (SQL
4ad0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
4ae0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4af0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
4b00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b10: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4b30: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4b40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b50: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4b60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4b70: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51  DLOCK        (SQ
4b80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
4b90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4ba0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
4bb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4bc0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
4bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c00: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4c30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c40: 28 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20  (12<<8))../*.** 
4c50: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
4c60: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
4c70: 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30  erations {F10230
4c80: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  }.**.** These bi
4c90: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
4ca0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
4cb0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
4cc0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
4cd0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
4ce0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
4cf0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
4d00: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f  ameter to the xO
4d10: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
4d20: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
4d30: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4d50: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
4d60: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
4d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4d80: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
4d90: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
4da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4db0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
4dc0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4de0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
4df0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
4e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4e10: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
4e20: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
4e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4e40: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
4e50: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
4e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4e70: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
4e80: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4ea0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
4eb0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
4ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4ed0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
4ee0: 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64     0x00000800.#d
4ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4f00: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
4f10: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
4f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4f30: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
4f40: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64     0x00002000.#d
4f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4f60: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
4f70: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f     0x00004000../
4f80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
4f90: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
4fa0: 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d 0a 2a  stics {F10240}.*
4fb0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4fc0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4fd0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4fe0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4ff0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5000: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5010: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5020: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5030: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5040: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5050: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5060: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5070: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5080: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5090: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
50a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
50b0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
50c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
50d0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
50e0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
50f0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5100: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5110: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5120: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5130: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5140: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5150: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5160: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5170: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5180: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5190: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
51a0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
51b0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
51c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
51d0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
51e0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
51f0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5200: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5210: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5220: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5230: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5240: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5250: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5260: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5270: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5280: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5290: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
52a0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
52b0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
52c0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
52d0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
52e0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
52f0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5300: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5310: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5320: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5330: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5340: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5350: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5370: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5380: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
53a0: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
53b0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
53c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
53d0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
53e0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
53f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5400: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5410: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5420: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5430: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5440: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5460: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5470: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5480: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5490: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
54a0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
54b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
54c0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
54d0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
54e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
54f0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5500: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5510: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5520: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 30  king Levels {F10
5530: 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  250}.**.** SQLit
5540: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
5550: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
5560: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
5570: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
5580: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
5590: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
55a0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
55b0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
55c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
55d0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
55f0: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
5620: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
5630: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
5640: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
5650: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
5660: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5680: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
5690: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
56a0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
56b0: 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b 46 31  n Type Flags {F1
56c0: 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  0260}.**.** When
56d0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
56e0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
56f0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
5700: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5710: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
5720: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
5730: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
5740: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
5750: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
5760: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
5770: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
5780: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
5790: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
57a0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
57b0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
57c0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
57d0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
57e0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
57f0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
5800: 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20  be flushed. The 
5810: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5820: 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a  AL flag means .*
5830: 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  * to use normal 
5840: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5850: 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  s. The SQLITE_SY
5860: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
5870: 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ns .** to use Ma
5880: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
5890: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
58a0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
58b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
58c0: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
58d0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
58e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
58f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
5900: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5910: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
5920: 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a     0x00010.../*.
5930: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5940: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
5950: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31  ile Handle {F111
5960: 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10}.**.** An [sq
5970: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
5980: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
5990: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
59a0: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
59b0: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
59c0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
59d0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
59e0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
59f0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
5a00: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
5a10: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
5a20: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
5a30: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
5a40: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
5a50: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
5a60: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
5a70: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5a80: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
5a90: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
5aa0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
5ab0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
5ac0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
5ad0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
5ae0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
5af0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
5b00: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
5b10: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
5b20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
5b30: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
5b40: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
5b50: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
5b60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
5b70: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
5b80: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
5b90: 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a  Object {F11120}.
5ba0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
5bb0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
5bc0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
5bd0: 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69  en method contai
5be0: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  ns a pointer to.
5bf0: 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** an instance o
5c00: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20  f this object.  
5c10: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
5c20: 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f  nes the.** metho
5c30: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
5c40: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
5c50: 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74 68  tions against th
5c60: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a  e open file..**.
5c70: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
5c80: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
5c90: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
5ca0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5cb0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
5cc0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
5cd0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
5ce0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
5cf0: 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63 6f  c()..*  The seco
5d00: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e 0a  nd choice is an.
5d10: 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75  ** OS-X style fu
5d20: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51 4c  llsync.  The SQL
5d30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c  ITE_SYNC_DATA fl
5d40: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5d50: 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74 65  n to.** indicate
5d60: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
5d70: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ata of the file 
5d80: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5d90: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a 2a  e needs to be.**
5da0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20   synced..** .** 
5db0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
5dc0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
5dd0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
5de0: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
5df0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5e00: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
5e10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5e20: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
5e30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
5e40: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
5e50: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
5e60: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
5e70: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5e80: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
5e90: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
5ea0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
5eb0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
5ec0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
5ed0: 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  .  .** The xChec
5ee0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
5ef0: 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20  method looks.** 
5f00: 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64 61  to see if any da
5f10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5f20: 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  n, either in thi
5f30: 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20  s.** process or 
5f40: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
5f50: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
5f60: 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a  g an RESERVED,.*
5f70: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
5f80: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
5f90: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
5fa0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
5fb0: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
5fc0: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66  sts and false if
5fd0: 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65   not..** .** The
5fe0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
5ff0: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
6000: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6010: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6020: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6030: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6040: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6050: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6060: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6070: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6080: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6090: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
60a0: 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ent.** is an int
60b0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20 54  eger opcode.   T
60c0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
60d0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
60e0: 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  c pointer which 
60f0: 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
6100: 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  e a pointer.** t
6110: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6120: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6130: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6140: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6150: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6160: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6170: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6180: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6190: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
61a0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
61b0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
61c0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
61d0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
61e0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
61f0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6200: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6210: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6220: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6230: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6240: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6250: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6260: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f 70  core reserves op
6270: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6280: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6290: 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c 49  use. .** A [SQLI
62a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
62b0: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
62c0: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
62d0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
62e0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
62f0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
6300: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
6310: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
6320: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a 2a  d use opcodes .*
6330: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
6340: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
6350: 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  licts..**.** The
6360: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
6370: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
6380: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
6390: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
63a0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
63b0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
63c0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
63d0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
63e0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
63f0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
6400: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
6410: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
6420: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
6430: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6440: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
6450: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
6460: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
6470: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
6480: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
6490: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
64a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
64b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
64c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
64d0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
64e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
64f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
6500: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6510: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
6520: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6530: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
6540: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6550: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
6560: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6570: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
6580: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6590: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
65a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
65c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
65d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
65e0: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
65f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6600: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
6610: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6620: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6630: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6640: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6650: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6660: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6670: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6680: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6690: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66a0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66b0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
66c0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
66d0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
66e0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
66f0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6700: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6710: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6720: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6730: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6740: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6750: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6760: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6770: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6780: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6790: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67a0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67b0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
67c0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
67d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
67e0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
67f0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6800: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6810: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6820: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6830: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6840: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
6850: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6860: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6870: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
6880: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
6890: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
68a0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
68b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
68c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
68d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
68e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
68f0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
6900: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
6910: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
6920: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
6930: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
6940: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
6950: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
6960: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
6970: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
6980: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
6990: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
69a0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
69b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
69c0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
69d0: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
69e0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
69f0: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
6a00: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
6a10: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
6a20: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
6a30: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6a40: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
6a50: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
6a60: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
6a70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6a80: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6a90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6aa0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6ab0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6ac0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6ad0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6ae0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6af0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6b00: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6b10: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
6b20: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6b30: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
6b40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6b50: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
6b60: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
6b70: 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F11310}.**.** Th
6b80: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
6b90: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
6ba0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
6bb0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
6bc0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6bd0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6be0: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
6bf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6c00: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6c10: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6c20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6c30: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6c40: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6c50: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
6c60: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
6c70: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6c80: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
6c90: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
6ca0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
6cb0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6cc0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6cd0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6ce0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6cf0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6d00: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6d10: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6d20: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6d30: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6d40: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6d50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6d60: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6d70: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6d80: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
6d90: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
6da0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
6db0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
6dc0: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
6dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6de0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6df0: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
6e00: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
6e10: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
6e20: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
6e30: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
6e40: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
6e50: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
6e60: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
6e70: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
6e80: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
6e90: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
6ea0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
6eb0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
6ec0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
6ed0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
6ee0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
6ef0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
6f00: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
6f10: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
6f20: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
6f30: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
6f40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
6f50: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
6f60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6f70: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
6f80: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
6f90: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
6fa0: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
6fb0: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
6fc0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6fd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6fe0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
6ff0: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
7000: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
7010: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
7020: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
7030: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7040: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7050: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7060: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7070: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7080: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7090: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
70a0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
70b0: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
70c0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
70d0: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
70e0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
70f0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
7100: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
7110: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
7120: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
7130: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7140: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7150: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7160: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7170: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7180: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7190: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
71a0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
71b0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
71c0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
71d0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
71e0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
71f0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7200: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7210: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7220: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7230: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7240: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7250: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7260: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7270: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7280: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7290: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
72a0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
72b0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
72c0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
72d0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
72e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
72f0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7300: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7310: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
7320: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7330: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7340: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7350: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7360: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7370: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7380: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7390: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
73a0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
73b0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
73c0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
73d0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
73e0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
73f0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7400: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7410: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7420: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7430: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7440: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7450: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7460: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7470: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7480: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
7490: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
74a0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
74b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
74c0: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
74d0: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
74e0: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
74f0: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
7500: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
7510: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
7520: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
7530: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7540: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7550: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
7560: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
7570: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
7580: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
7590: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
75a0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
75b0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
75c0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
75d0: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
75e0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
75f0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
7600: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
7610: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
7620: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7630: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7640: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7650: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7660: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7670: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7680: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
7690: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
76a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
76b0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
76c0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
76d0: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
76e0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
76f0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
7700: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
7710: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
7720: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
7730: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7740: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7750: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
7760: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
7770: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
7780: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
7790: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
77a0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
77b0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
77c0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
77d0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
77e0: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
77f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7800: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
7810: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7820: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
7830: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7840: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7850: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7860: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7870: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
7890: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
78a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
78b0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
78c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
78d0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
78e0: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
78f0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
7900: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
7910: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
7920: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
7930: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7940: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7950: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7960: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7970: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7980: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
7990: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
79a0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
79b0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
79c0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
79d0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
79e0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
79f0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
7a00: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
7a10: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
7a20: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
7a30: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
7a40: 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  rn .** SQLITE_IO
7a50: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7a60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7a70: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7a80: 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
7a90: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
7aa0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
7ab0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7ac0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7ad0: 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  dom .** order an
7ae0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
7af0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
7b00: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
7b10: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
7b20: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7b30: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7b40: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
7b50: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
7b60: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7b70: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7b80: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
7b90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
7ba0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
7bb0: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d  .** .** {F11145}
7bc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7bd0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7be0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7bf0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
7c00: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
7c10: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46  t is closed.  {F
7c20: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
7c30: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7c40: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
7c50: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
7c60: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
7c70: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
7c80: 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31  ournals. .** {F1
7c90: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
7ca0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7cb0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
7cc0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7cd0: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
7ce0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
7cf0: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
7d00: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
7d10: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
7d20: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
7d30: 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  file. {END}.** .
7d40: 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c  ** {F11148} At l
7d50: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
7d60: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
7d70: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
7d80: 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c  QLite .** to hol
7d90: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
7da0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
7db0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
7dc0: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ird .** argument
7dd0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44   to xOpen.  {END
7de0: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
7df0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
7e00: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
7e10: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
7e20: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
7e30: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a  ill it in..** .*
7e40: 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66  * {F11149} The f
7e50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7e60: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7e70: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7e80: 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20  _EXISTS] .** to 
7e90: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
7ea0: 73 74 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stance of a file
7eb0: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
7ec0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
7ed0: 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  ] to test to see
7ee0: 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73  .** if a file is
7ef0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
7f00: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
7f10: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
7f20: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  ** to test to se
7f30: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61  e if a file is a
7f40: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
7f50: 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c  .  {END} The fil
7f60: 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64  e can be a .** d
7f70: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a  irectory..** .**
7f80: 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65   {F11150} SQLite
7f90: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
7fa0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
7fb0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
7fc0: 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74  s for.** the out
7fd0: 70 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 20  put buffers for 
7fe0: 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64  xGetTempname and
7ff0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8000: 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65 78 61  {F11151} The exa
8010: 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68  ct.** size of th
8020: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  e output buffer 
8030: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
8040: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
8050: 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64   both .** method
8060: 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65 20  s. {END} If the 
8070: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73  output buffer is
8080: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
8090: 68 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  h, SQLITE_CANTOP
80a0: 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  EN.** should be 
80b0: 72 65 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69  returned. As thi
80c0: 73 20 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20  s is handled as 
80d0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
80e0: 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20   SQLite,.** vfs 
80f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8100: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 20  should endeavor 
8110: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
8120: 62 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d  by setting .** m
8130: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
8140: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
8150: 65 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20  e value..** .** 
8160: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
8170: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64  ), xSleep(), and
8180: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
8190: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
81a0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
81b0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
81c0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
81d0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
81e0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
81f0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
8200: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
8210: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
8220: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
8230: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
8240: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
8250: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
8260: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
8270: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
8280: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
8290: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
82a0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
82b0: 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a   obtained.  The.
82c0: 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  ** xSleep() meth
82d0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
82e0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
82f0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
8300: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
8310: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
8320: 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75   given.  The xCu
8330: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
8340: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8350: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
8360: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
8370: 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69  t date and.** ti
8380: 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  me..*/.typedef s
8390: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
83a0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
83b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
83c0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
83d0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
83e0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
83f0: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  ion number */.  
8400: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
8410: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
8420: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
8430: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
8440: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
8450: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
8460: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
8470: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
8480: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
8490: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
84a0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
84b0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
84c0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
84d0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
84e0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
84f0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
8500: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
8510: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
8520: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
8530: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
8540: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
8550: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8560: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
8570: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
8580: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
8590: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
85a0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
85b0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
85c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
85d0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
85e0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
85f0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
8600: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8610: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 29  Name, int flags)
8620: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54 65  ;.  int (*xGetTe
8630: 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  mpname)(sqlite3_
8640: 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  vfs*, int nOut, 
8650: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
8660: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
8670: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8680: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
8690: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
86a0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
86b0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
86c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
86d0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
86e0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
86f0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
8700: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
8710: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
8720: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79  .  void *(*xDlSy
8730: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
8740: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
8750: 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76  r *zSymbol);.  v
8760: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
8770: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
8780: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
8790: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
87a0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
87b0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
87c0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
87d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
87e0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
87f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
8800: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
8810: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
8820: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
8830: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
8840: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
8850: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
8860: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
8870: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
8880: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
8890: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
88a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
88b0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
88c0: 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31 31  VFS method {F111
88d0: 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39  90}.**.** {F1119
88e0: 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  1} These integer
88f0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
8900: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
8910: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
8920: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
8930: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
8940: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
8950: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
8960: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
8970: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
8980: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
8990: 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f   method is.** lo
89a0: 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46 31 31  oking for.  {F11
89b0: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45  192} With SQLITE
89c0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
89d0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
89e0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
89f0: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68  cks to see if th
8a00: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 20 7b  e file exists. {
8a10: 46 31 31 31 39 33 7d 20 57 69 74 68 0a 2a 2a 20  F11193} With.** 
8a20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8a30: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
8a40: 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63  cess method chec
8a50: 6b 73 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20  ks to see.** if 
8a60: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
8a70: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
8a80: 69 74 61 62 6c 65 2e 20 20 7b 46 31 31 31 39 34  itable.  {F11194
8a90: 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  } With.** SQLITE
8aa0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 74 68 65  _ACCESS_READ the
8ab0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8ac0: 2a 2a 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65  ** checks to see
8ad0: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
8ae0: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
8af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8b00: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
8b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
8b20: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
8b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8b40: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
8b50: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
8b60: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
8b70: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
8b80: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32  esult Codes {F12
8b90: 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200}.**.** The s
8ba0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
8bb0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
8bc0: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
8bd0: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
8be0: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
8bf0: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
8c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
8c10: 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
8c20: 0a 2a 2a 20 54 68 65 20 65 78 74 65 6e 64 65 64  .** The extended
8c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
8c40: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
8c50: 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
8c60: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
8c70: 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ility..**.** INV
8c80: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
8c90: 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  F12201} Each new
8ca0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
8cb0: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
8cc0: 65 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  e the .**       
8cd0: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
8ce0: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
8cf0: 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  re.**          d
8d00: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
8d10: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30  lt..**.** {F1220
8d20: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
8d30: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
8d40: 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65  codes(D,F)] inte
8d50: 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62  rface shall enab
8d60: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
8d70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8d80: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 0a  codes] for the .
8d90: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
8da0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8db0: 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61 72  ] D if the F par
8dc0: 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
8dd0: 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64     is true, or d
8de0: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46  isable them if F
8df0: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
8e00: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
8e10: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
8e20: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
8e30: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
8e40: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
8e50: 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30  rt Rowid {F12220
8e60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  }.**.** Each ent
8e70: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
8e80: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
8e90: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
8ea0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
8eb0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
8ec0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
8ed0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
8ee0: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
8ef0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
8f00: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
8f10: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
8f20: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
8f30: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
8f40: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
8f50: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
8f60: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
8f70: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
8f80: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
8f90: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
8fa0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
8fb0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
8fc0: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
8fd0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
8fe0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
8ff0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
9000: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
9010: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
9020: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
9030: 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  e from the datab
9040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
9050: 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66  * shown in the f
9060: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
9070: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
9080: 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76 65   inserts.** have
9090: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
90a0: 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  n this database 
90b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
90c0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
90d0: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
90e0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
90f0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
9100: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a  he rowid of the.
9110: 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  ** inserted row 
9120: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
9130: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
9140: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
9150: 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  er.** is running
9160: 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  .  But once the 
9170: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
9180: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
9190: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69  turned.** by thi
91a0: 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
91b0: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
91c0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
91d0: 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67  ore the.** trigg
91e0: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  er fired..**.** 
91f0: 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66  An INSERT that f
9200: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
9210: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
9220: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
9230: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74  uccessful insert
9240: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
9250: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
9260: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
9270: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
9280: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
9290: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
92a0: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
92b0: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
92c0: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
92d0: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
92e0: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
92f0: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
9300: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
9310: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
9320: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
9330: 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e  R REPLACE .** en
9340: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
9350: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
9360: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
9370: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
9380: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
9390: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
93a0: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
93b0: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
93c0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
93d0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
93e0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
93f0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
9400: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
9410: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
9420: 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  e. .**.** For th
9430: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
9440: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69  is routine, an i
9450: 6e 73 65 72 74 20 69 73 20 63 6f 6e 73 69 64 65  nsert is conside
9460: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
9470: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
9480: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
9490: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
94a0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
94b0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d  :.**.** {F12221}
94c0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
94d0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
94e0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
94f0: 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
9500: 20 20 20 20 72 6f 77 69 64 20 6f 66 20 74 68 65      rowid of the
9510: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
9520: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 64  cessful insert d
9530: 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  one.**          
9540: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
9550: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
9560: 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
9570: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
9580: 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 20  or higher level 
9590: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
95a0: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
95b0: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  e have.**       
95c0: 20 20 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69     been no quali
95d0: 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a  fying inserts..*
95e0: 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20 54 68  *.** {F12223} Th
95f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
9600: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
9610: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
9620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d  .**          sam
9630: 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c  e value when cal
9640: 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
9650: 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  e trigger contex
9660: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d  t.**          im
9670: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
9680: 20 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c   and after a ROL
9690: 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  LBACK..**.** LIM
96a0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
96b0: 7b 55 31 32 32 33 32 7d 20 49 66 20 61 20 73 65  {U12232} If a se
96c0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 64 6f  parate thread do
96d0: 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20  es a new insert 
96e0: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
96f0: 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
9700: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
9710: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
9720: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
9730: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
9740: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
9750: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
9760: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
9770: 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20  sert rowid,.**  
9780: 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
9790: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
97a0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
97b0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
97c0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
97d0: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
97e0: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
97f0: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
9800: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20   or the new.**  
9810: 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73          last ins
9820: 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71  ert rowid..*/.sq
9830: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
9840: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
9850: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
9860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9870: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
9880: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
9890: 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a  ied {F12240}.**.
98a0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
98b0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
98c0: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
98d0: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
98e0: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
98f0: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
9900: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
9910: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
9920: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
9930: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
9940: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
9950: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
9960: 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68  ter.  Only.** ch
9970: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
9980: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
9990: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  d by the INSERT,
99a0: 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44   UPDATE, or.** D
99b0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
99c0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
99d0: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
99e0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
99f0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
9a00: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
9a10: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
9a20: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
9a30: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
9a40: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
9a50: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
9a60: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
9a70: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
9a80: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
9a90: 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
9aa0: 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
9ab0: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
9ac0: 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
9ad0: 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
9ae0: 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
9af0: 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
9b00: 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
9b10: 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
9b20: 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
9b30: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
9b40: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
9b50: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
9b60: 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72  , DROP TABLE, or
9b70: 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
9b80: 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
9b90: 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
9ba0: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ct row changes..
9bb0: 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
9bc0: 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
9bd0: 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
9be0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
9bf0: 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
9c00: 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74  he script of a t
9c10: 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51  rigger.  Most SQ
9c20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
9c30: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
9c40: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
9c50: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
9c60: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
9c70: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
9c80: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
9c90: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
9ca0: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
9cb0: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
9cc0: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
9cd0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
9ce0: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
9cf0: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
9d00: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
9d10: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
9d20: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
9d30: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
9d40: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
9d50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
9d60: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
9d70: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
9d80: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
9d90: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
9da0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
9db0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
9dc0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
9dd0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
9de0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
9df0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
9e00: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
9e10: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
9e20: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
9e30: 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e 20 63 61  **.** So when ca
9e40: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
9e50: 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
9e60: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
9e70: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
9e80: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
9e90: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
9ea0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
9eb0: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
9ec0: 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
9ed0: 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a 2a 2a 20  e top level..** 
9ee0: 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
9ef0: 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  of a trigger, th
9f00: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
9f10: 73 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  s() interface.**
9f20: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
9f30: 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
9f40: 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
9f50: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
9f60: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
9f70: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
9f80: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
9f90: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
9fa0: 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
9fb0: 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
9fc0: 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
9fd0: 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
9fe0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69 6e 20 63  not include in c
9ff0: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
a000: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
a010: 73 69 6e 63 65 20 74 68 65 79 20 68 61 76 65 20  since they have 
a020: 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
a030: 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
a040: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
a050: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46  ommand "DELETE F
a060: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f  ROM table" witho
a070: 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c  ut.** a WHERE cl
a080: 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67  ause by dropping
a090: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20   and recreating 
a0a0: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69  the table.  (Thi
a0b0: 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73  s is much.** fas
a0c0: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 20 74  ter than going t
a0d0: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74  hrough and delet
a0e0: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65  ing individual e
a0f0: 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65  lements from the
a100: 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42 65 63  .** table.)  Bec
a110: 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f 70 74  ause of this opt
a120: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64  imization, the d
a130: 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 22  eletions in.** "
a140: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
a150: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63  e" are not row c
a160: 68 61 6e 67 65 73 20 61 6e 64 20 77 69 6c 6c 20  hanges and will 
a170: 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 0a 2a  not be counted.*
a180: 2a 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  * by the sqlite3
a190: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73  _changes() or [s
a1a0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
a1b0: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
a1c0: 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20 61 6e 20  s..** To get an 
a1d0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
a1e0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
a1f0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
a200: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
a210: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
a220: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
a230: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
a240: 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65 20 5b  * {F12241} The [
a250: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
a260: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
a270: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
a280: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  f.**          ro
a290: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
a2a0: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
a2b0: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
a2c0: 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  TE,.**          
a2d0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
a2e0: 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ent on the same 
a2f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a300: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
a310: 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73      within the s
a320: 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74  ame trigger cont
a330: 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
a340: 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20  there have.**   
a350: 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20         not been 
a360: 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20 72  any qualifying r
a370: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
a380: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
a390: 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d 20 49 66  *.** {U12252} If
a3a0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
a3b0: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
a3c0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
a3d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
a3e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
a3f0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
a400: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
a410: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
a420: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
a430: 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69        is unpredi
a440: 63 74 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65 61  ctable and unmea
a450: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
a460: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
a470: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
a480: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
a490: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
a4a0: 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 36   Modified {F1226
a4b0: 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  0}.***.** This f
a4c0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
a4d0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
a4e0: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
a4f0: 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54 2c 20 55  .** by INSERT, U
a500: 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
a510: 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
a520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
a530: 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e  ndle.** was open
a540: 65 64 2e 20 20 54 68 65 20 63 6f 75 6e 74 20 69  ed.  The count i
a550: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
a560: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69  ges from all tri
a570: 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65 78 74 73  gger.** contexts
a580: 2e 20 20 42 75 74 20 74 68 65 20 63 6f 75 6e 74  .  But the count
a590: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
a5a0: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
a5b0: 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 52  o.** implement R
a5c0: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
a5d0: 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  ts, do rollbacks
a5e0: 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
a5f0: 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44 52 4f 50  sing,.** or DROP
a600: 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e   table processin
a610: 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65  g..** The change
a620: 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64  s.** are counted
a630: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
a640: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
a650: 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
a660: 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77 68 65 6e  pleted .** (when
a670: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
a680: 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20  andle is passed 
a690: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
a6a0: 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71 6c  t()] or .** [sql
a6b0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
a6c0: 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  )..**.** SQLite 
a6d0: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
a6e0: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46  ommand "DELETE F
a6f0: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f  ROM table" witho
a700: 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c  ut.** a WHERE cl
a710: 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67  ause by dropping
a720: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20   and recreating 
a730: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69  the table.  (Thi
a740: 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73  s is much.** fas
a750: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
a760: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
a770: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
a780: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
a790: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
a7a0: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20  ause of.** this 
a7b0: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
a7c0: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66  e change count f
a7d0: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  or "DELETE FROM 
a7e0: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a  table" will be.*
a7f0: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73  * zero regardles
a800: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
a810: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
a820: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
a830: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65   in the.** table
a840: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75  . To get an accu
a850: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
a860: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
a870: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
a880: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
a890: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
a8a0: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tead..**.** See 
a8b0: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
a8c0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
a8d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  erface..**.** IN
a8e0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a  VARIANTS:.** .**
a8f0: 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20 5b 73   {F12261} The [s
a900: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
a910: 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20  nges()] returns 
a920: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
a930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
a940: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
a950: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
a960: 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c  DATE, and/or DEL
a970: 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ETE.**          
a980: 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68  statements on th
a990: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
a9a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e   connection], in
a9b0: 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20   any.**         
a9c0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
a9d0: 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  , since the data
a9e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
a9f0: 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
aa00: 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c  created..**.** L
aa10: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
aa20: 2a 20 7b 55 31 32 32 36 34 7d 20 49 66 20 61 20  * {U12264} If a 
aa30: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
aa40: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
aa50: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
aa60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
aa70: 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20            while 
aa80: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
aa90: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
aaa0: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
aab0: 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue .**         
aac0: 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
aad0: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 75  redictable and u
aae0: 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a  nmeaningful..*/.
aaf0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
ab00: 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
ab10: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ab20: 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
ab30: 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
ab40: 75 65 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a 2a  uery {F12270}.**
ab50: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
ab60: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
ab70: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
ab80: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
ab90: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
aba0: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
abb0: 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
abc0: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
abd0: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
abe0: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
abf0: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
ac00: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
ac10: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
ac20: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
ac30: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
ac40: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
ac50: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
ac60: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  iately..**.** It
ac70: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
ac80: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
ac90: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
aca0: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
acb0: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
acc0: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
acd0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
ace0: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
acf0: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
ad00: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
ad10: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61  outine with a da
ad20: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ad30: 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  n that.** is clo
ad40: 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
ad50: 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
ad60: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
ad70: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
ad80: 61 6e 20 53 51 4c 20 69 73 20 76 65 72 79 20 6e  an SQL is very n
ad90: 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
ada0: 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20  t the time when 
adb0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
adc0: 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64  t().** is called
add0: 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
ade0: 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
adf0: 72 74 75 6e 69 74 79 20 74 6f 20 62 65 20 69 6e  rtunity to be in
ae00: 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a 20 49 74  terrupted..** It
ae10: 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
ae20: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
ae30: 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  * An SQL operati
ae40: 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
ae50: 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
ae60: 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  rn.** [SQLITE_IN
ae70: 54 45 52 52 55 50 54 5d 2e 20 20 49 66 20 74 68  TERRUPT].  If th
ae80: 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
ae90: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
aea0: 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20 55 50 44  n.** INSERT, UPD
aeb0: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 74  ATE, or DELETE t
aec0: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
aed0: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
aee0: 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65 6e 20  ction, .** then 
aef0: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
af00: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72  action will be r
af10: 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
af20: 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20 41 20 63  atically..** A c
af30: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
af40: 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e  nterrupt() has n
af50: 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
af60: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
af70: 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
af80: 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74  fter sqlite3_int
af90: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
afa0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
afb0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37  TS:.**.** {F1227
afc0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
afd0: 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74  interrupt()] int
afe0: 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63  erface will forc
aff0: 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a  e all running.**
b000: 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74            SQL st
b010: 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
b020: 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d  ted with the sam
b030: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
b040: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
b050: 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20    to halt after 
b060: 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f  processing at mo
b070: 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61  st one additiona
b080: 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20  l row of.**     
b090: 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a       data..**.**
b0a0: 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {F12272} Any SQ
b0b0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
b0c0: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
b0d0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
b0e0: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
b0f0: 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
b100: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
b110: 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  PT]..**.** LIMIT
b120: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
b130: 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
b140: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b150: 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
b160: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
b170: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
b180: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
b190: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
b1a0: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
b1b0: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
b1c0: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
b1d0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
b1e0: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
b1f0: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
b200: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
b210: 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10510}.**.** T
b220: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
b230: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
b240: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
b250: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
b260: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
b270: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
b280: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
b290: 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
b2a0: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
b2b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
b2c0: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
b2d0: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
b2e0: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
b2f0: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
b300: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
b310: 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
b320: 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
b330: 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
b340: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
b350: 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
b360: 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
b370: 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
b380: 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
b390: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
b3a0: 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
b3b0: 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
b3c0: 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
b3d0: 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
b3e0: 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
b3f0: 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
b400: 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
b410: 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
b420: 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
b430: 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
b440: 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
b450: 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
b460: 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
b470: 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
b480: 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
b490: 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
b4a0: 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
b4b0: 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
b4c0: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
b4d0: 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
b4e0: 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 61 6e  parse the SQL an
b4f0: 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e 6f 74  d.** so will not
b500: 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
b510: 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
b520: 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  SQL..**.** INVAR
b530: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
b540: 30 35 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65  0511} The sqlite
b550: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 61 6e 64  3_complete() and
b560: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
b570: 65 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  e16() functions.
b580: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
b590: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
b5a0: 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  o) if and only i
b5b0: 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 20 20  f the last.**   
b5c0: 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68 69 74 65         non-white
b5d0: 73 70 61 63 65 20 74 6f 6b 65 6e 20 69 6e 20 74  space token in t
b5e0: 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20  heir input is a 
b5f0: 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 0a 2a  semicolon that.*
b600: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
b610: 74 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68 65  t in between the
b620: 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f   BEGIN and END o
b630: 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47  f a CREATE TRIGG
b640: 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ER.**          s
b650: 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
b660: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
b670: 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54 68 65 20  ** {U10512} The 
b680: 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33  input to sqlite3
b690: 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d 75 73 74  _complete() must
b6a0: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
b6b0: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
b6c0: 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
b6d0: 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33 7d 20 54  **.** {U10513} T
b6e0: 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69  he input to sqli
b6f0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
b700: 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
b710: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
b720: 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73 74         UTF-16 st
b730: 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
b740: 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
b750: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
b760: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
b770: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
b780: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
b790: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
b7a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
b7b0: 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
b7c0: 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
b7d0: 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20  ITE_BUSY Errors 
b7e0: 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12310}.**.** T
b7f0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e  his routine iden
b800: 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63  tifies a callbac
b810: 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
b820: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69 6e 76 6f  might be.** invo
b830: 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
b840: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
b850: 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
b860: 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61  se table .** tha
b870: 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
b880: 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
b890: 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68  locked..** If th
b8a0: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
b8b0: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
b8c0: 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
b8d0: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
b8e0: 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
b8f0: 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
b900: 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
b910: 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a  ering the lock..
b920: 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63  ** If the busy c
b930: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e  allback is not N
b940: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ULL, then the.**
b950: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
b960: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b970: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  wo arguments.  T
b980: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
b990: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
b9a0: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
b9b0: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
b9c0: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
b9d0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
b9e0: 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  t to this routin
b9f0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  e.  The second a
ba00: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
ba10: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65  e handler is the
ba20: 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
ba30: 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
ba40: 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
ba50: 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
ba60: 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
ba70: 74 2e 20 20 20 49 66 20 74 68 65 0a 2a 2a 20 62  t.   If the.** b
ba80: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
ba90: 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
baa0: 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
bab0: 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
bac0: 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
bad0: 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
bae0: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
baf0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
bb00: 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
bb10: 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
bb20: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
bb30: 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
bb40: 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
bb50: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
bb60: 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
bb70: 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
bb80: 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
bb90: 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
bba0: 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
bbb0: 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
bbc0: 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20  ntee that.** it 
bbd0: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
bbe0: 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
bbf0: 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a  ck contention..*
bc00: 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  * If SQLite dete
bc10: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
bc20: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
bc30: 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
bc40: 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c  lt in.** a deadl
bc50: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
bc60: 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
bc70: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
bc80: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
bc90: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
bca0: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
bcb0: 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
bcc0: 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
bcd0: 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
bce0: 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
bcf0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
bd00: 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
bd10: 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
bd20: 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
bd30: 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
bd40: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
bd50: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
bd60: 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
bd70: 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
bd80: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
bd90: 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
bda0: 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
bdb0: 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
bdc0: 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
bdd0: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
bde0: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
bdf0: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
be00: 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
be10: 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
be20: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
be30: 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
be40: 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
be50: 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
be60: 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
be70: 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
be80: 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
be90: 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
bea0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
beb0: 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
bec0: 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
bed0: 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
bee0: 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
bef0: 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
bf00: 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
bf10: 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
bf20: 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
bf30: 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
bf40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
bf50: 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
bf60: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
bf70: 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
bf80: 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
bf90: 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
bfa0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
bfb0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
bfc0: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
bfd0: 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
bfe0: 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
bff0: 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
c000: 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
c010: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
c020: 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
c030: 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
c040: 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
c050: 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
c060: 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
c070: 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
c080: 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
c090: 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
c0a0: 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
c0b0: 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
c0c0: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
c0d0: 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
c0e0: 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
c0f0: 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66  .** readers.  If
c100: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
c110: 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
c120: 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
c130: 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
c140: 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
c150: 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
c160: 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
c170: 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
c180: 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
c190: 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
c1a0: 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
c1b0: 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
c1c0: 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
c1d0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
c1e0: 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64    This error cod
c1f0: 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
c200: 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
c210: 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
c220: 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
c230: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
c240: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69  "http://www.sqli
c250: 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77  te.org/cvstrac/w
c260: 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
c270: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
c280: 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
c290: 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
c2a0: 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
c2b0: 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
c2c0: 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
c2d0: 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
c2e0: 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65 20 63 61  .**..** There ca
c2f0: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
c300: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
c310: 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
c320: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
c330: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e  nection.  Settin
c340: 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
c350: 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20  dler clears any 
c360: 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 20 0a 2a  previous one. .*
c370: 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c  * Note that call
c380: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
c390: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c  y_timeout()] wil
c3a0: 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
c3b0: 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ear.** the busy 
c3c0: 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  handler..**.** I
c3d0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
c3e0: 20 7b 46 31 32 33 31 31 7d 20 54 68 65 20 5b 73   {F12311} The [s
c3f0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
c400: 6c 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ler()] function 
c410: 72 65 70 6c 61 63 65 73 20 74 68 65 20 62 75 73  replaces the bus
c420: 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20 20  y handler.**    
c430: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69        callback i
c440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
c450: 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69  onnection identi
c460: 66 69 65 64 20 62 79 20 74 68 65 20 31 73 74 0a  fied by the 1st.
c470: 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
c480: 6d 65 74 65 72 20 77 69 74 68 20 61 20 6e 65 77  meter with a new
c490: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 64   busy handler id
c4a0: 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
c4b0: 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20 20  2nd and 3rd.**  
c4c0: 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
c4d0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  rs..**.** {F1231
c4e0: 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  2} The default b
c4f0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
c500: 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
c510: 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c 4c  nections is NULL
c520: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34 7d  ..**.** {F12314}
c530: 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72   When two or mor
c540: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c550: 63 74 69 6f 6e 20 73 68 61 72 65 20 61 20 63 6f  ction share a co
c560: 6d 6d 6f 6e 20 63 61 63 68 65 2c 0a 2a 2a 20 20  mmon cache,.**  
c570: 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79          the busy
c580: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65   handler for the
c590: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
c5a0: 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75  tion currently u
c5b0: 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
c5c0: 20 74 68 65 20 63 61 63 68 65 20 69 73 20 69 6e   the cache is in
c5d0: 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63  voked when the c
c5e0: 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20  ache encounters 
c5f0: 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  a lock..**.** {F
c600: 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79  12316} If a busy
c610: 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
c620: 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  k returns zero, 
c630: 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 0a  then the SQLite.
c640: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
c650: 72 66 61 63 65 20 74 68 61 74 20 70 72 6f 76 6f  rface that provo
c660: 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20  ked the locking 
c670: 65 76 65 6e 74 20 77 69 6c 6c 20 72 65 74 75 72  event will retur
c680: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
c690: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
c6a0: 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51 4c 69  ** {F12318} SQLi
c6b0: 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73 20  te will invokes 
c6c0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
c6d0: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
c6e0: 6e 74 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  nt which.**     
c6f0: 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20       are a copy 
c700: 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73  of the pointer s
c710: 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33  upplied by the 3
c720: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
c730: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
c740: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
c750: 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74  r()] and a count
c760: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
c770: 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  f prior.**      
c780: 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20      invocations 
c790: 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  of the busy hand
c7a0: 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ler for the same
c7b0: 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a   locking event..
c7c0: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
c7d0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31 39  S:.**.** {U12319
c7e0: 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  } A busy handler
c7f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
c800: 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
c810: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
c820: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 70 72  *          or pr
c830: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
c840: 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
c850: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
c860: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
c870: 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
c880: 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
c890: 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
c8a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c8b0: 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
c8c0: 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a  eout {F12340}.**
c8d0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
c8e0: 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
c8f0: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
c900: 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 0a 2a 2a  busy handler].**
c910: 20 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72   that sleeps for
c920: 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a   a while when a.
c930: 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b  ** table is lock
c940: 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72  ed.  The handler
c950: 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
c960: 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
c970: 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22 6d   .** at least "m
c980: 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
c990: 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76 65  of sleeping have
c9a0: 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b 46 31 32   been done. {F12
c9b0: 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a 20 22 6d  343} After.** "m
c9c0: 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
c9d0: 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65  of sleeping, the
c9e0: 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
c9f0: 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73   0 which.** caus
ca00: 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
ca10: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53  ()] to return [S
ca20: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
ca30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
ca40: 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
ca50: 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
ca60: 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
ca70: 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
ca80: 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
ca90: 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
caa0: 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
cab0: 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
cac0: 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
cad0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
cae0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
caf0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
cb00: 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ion.  If another
cb10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61   busy handler wa
cb20: 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28  s defined  .** (
cb30: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
cb40: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
cb50: 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
cb60: 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
cb70: 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
cb80: 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
cb90: 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ared..**.** INVA
cba0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
cbb0: 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12341} The [sqli
cbc0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
cbd0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76 65  ()] function ove
cbe0: 72 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f 72  rrides any prior
cbf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
cc00: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
cc10: 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ut()] or [sqlite
cc20: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
cc30: 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  ] setting.**    
cc40: 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
cc50: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
cc60: 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ction..**.** {F1
cc70: 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64  2343} If the 2nd
cc80: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
cc90: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
cca0: 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74  out()] is less t
ccb0: 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
ccc0: 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
ccd0: 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20  , then the busy 
cce0: 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
ccf0: 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20  ed so that.**   
cd00: 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65         all subse
cd10: 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76  quent locking ev
cd20: 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79  ents immediately
cd30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
cd40: 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  BUSY]..**.** {F1
cd50: 32 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64  2344} If the 2nd
cd60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
cd70: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
cd80: 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69  out()] is a posi
cd90: 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
cda0: 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20   number N, then 
cdb0: 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  a busy handler i
cdc0: 73 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61  s set that repea
cdd0: 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20  tedly calls.**  
cde0: 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65          the xSle
cdf0: 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74  ep() method in t
ce00: 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  he VFS interface
ce10: 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
ce20: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f  e.**          lo
ce30: 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74  ck clears or unt
ce40: 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76  il the cumulativ
ce50: 65 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65 70  e sleep time rep
ce60: 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20 20  orted back.**   
ce70: 20 20 20 20 20 20 20 62 79 20 78 53 6c 65 65 70         by xSleep
ce80: 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c  () exceeds N mil
ce90: 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e  liseconds..*/.in
cea0: 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
ceb0: 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
cec0: 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
ced0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
cee0: 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
cef0: 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
cf00: 69 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a  ies {F12370}.**.
cf10: 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
cf20: 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
cf30: 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
cf40: 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
cf50: 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
cf60: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
cf70: 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
cf80: 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
cf90: 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
cfa0: 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
cfb0: 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
cfc0: 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
cfd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
cfe0: 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
cff0: 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
d000: 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
d010: 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
d020: 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
d030: 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
d040: 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
d050: 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
d060: 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
d070: 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
d080: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
d090: 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
d0a0: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
d0b0: 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
d0c0: 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
d0d0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
d0e0: 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
d0f0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
d100: 2d 38 20 73 74 72 69 6e 67 73 2e 20 20 54 68 65  -8 strings.  The
d110: 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
d120: 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
d130: 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68 65 20 66  rray.  .** The f
d140: 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
d150: 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f 2d 74 65  point to zero-te
d160: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
d170: 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e 74 61 69   that .** contai
d180: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
d190: 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
d1a0: 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
d1b0: 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
d1c0: 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
d1d0: 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c 75 65 73    NULL.** values
d1e0: 20 61 72 65 20 67 69 76 65 20 61 20 4e 55 4c 4c   are give a NULL
d1f0: 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c 6c 20 6f   pointer.  All o
d200: 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
d210: 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55 54 46 2d  in.** their UTF-
d220: 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
d230: 64 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  d string represe
d240: 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
d250: 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
d260: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
d270: 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
d280: 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
d290: 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65 20 6f 72  nsists of one or
d2a0: 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
d2b0: 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
d2c0: 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
d2d0: 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
d2e0: 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
d2f0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
d300: 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
d310: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
d320: 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
d330: 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
d340: 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
d350: 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
d360: 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
d370: 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
d380: 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
d390: 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
d3a0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
d3b0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
d3c0: 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
d3d0: 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
d3e0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
d3f0: 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
d400: 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
d410: 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
d420: 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
d430: 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
d440: 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
d450: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
d460: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
d470: 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
d480: 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
d490: 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
d4a0: 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
d4b0: 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
d4c0: 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
d4d0: 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
d4e0: 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
d4f0: 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
d500: 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
d510: 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
d520: 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
d530: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
d540: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
d550: 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
d560: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
d570: 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
d580: 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
d590: 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
d5a0: 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
d5b0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
d5c0: 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
d5d0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
d5e0: 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
d5f0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d600: 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
d610: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d620: 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
d630: 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
d640: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
d650: 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
d660: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
d670: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
d680: 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
d690: 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
d6a0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
d6b0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
d6c0: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
d6d0: 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
d6e0: 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
d6f0: 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
d700: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
d710: 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  It returns a res
d720: 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
d730: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
d740: 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
d750: 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
d760: 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
d770: 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
d780: 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
d790: 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
d7a0: 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  d .** pass the p
d7b0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
d7c0: 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
d7d0: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
d7e0: 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a  () in order to .
d7f0: 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
d800: 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
d810: 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 75  alloc-ed.  Becau
d820: 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
d830: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  e .** [sqlite3_m
d840: 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
d850: 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
d860: 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
d870: 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
d880: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
d890: 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
d8a0: 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
d8b0: 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a 2a 20 5b  tly.  Only .** [
d8c0: 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
d8d0: 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
d8e0: 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
d8f0: 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
d900: 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
d910: 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
d920: 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
d930: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
d940: 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
d950: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
d960: 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
d970: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d980: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
d990: 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
d9a0: 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
d9b0: 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
d9c0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
d9d0: 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
d9e0: 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
d9f0: 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
da00: 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
da10: 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
da20: 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
da30: 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
da40: 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
da50: 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
da60: 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
da70: 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
da80: 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
da90: 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
daa0: 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
dab0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
dac0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  g()]..**.** INVA
dad0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
dae0: 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c  12371} If a [sql
daf0: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
db00: 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79  ] fails a memory
db10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
db20: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
db30: 20 66 72 65 65 73 20 74 68 65 20 72 65 73 75 6c   frees the resul
db40: 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f  t table under co
db50: 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72  nstruction, abor
db60: 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
db70: 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63     query in proc
db80: 65 73 73 2c 20 73 6b 69 70 73 20 61 6e 79 20 73  ess, skips any s
db90: 75 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65  ubsequent querie
dba0: 73 2c 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 20  s, sets the.**  
dbb0: 20 20 20 20 20 20 20 20 2a 72 65 73 75 6c 74 70          *resultp
dbc0: 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20   output pointer 
dbd0: 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75  to NULL and retu
dbe0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  rns [SQLITE_NOME
dbf0: 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  M]..**.** {F1237
dc00: 33 7d 20 49 66 20 74 68 65 20 6e 63 6f 6c 75 6d  3} If the ncolum
dc10: 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  n parameter to [
dc20: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
dc30: 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
dc40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
dc50: 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  n [sqlite3_get_t
dc60: 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68  able()] write th
dc70: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
dc80: 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  mns in the.**   
dc90: 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
dca0: 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
dcb0: 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20  nto *ncolumn if 
dcc0: 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20  the query is.** 
dcd0: 20 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73           success
dce0: 66 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63  ful (if the func
dcf0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c  tion returns SQL
dd00: 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK)..**.** {
dd10: 46 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 6e  F12374} If the n
dd20: 72 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f  row parameter to
dd30: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
dd40: 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55  ble()] is not NU
dd50: 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
dd60: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  hen [sqlite3_get
dd70: 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20  _table()] write 
dd80: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
dd90: 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ws in the.**    
dda0: 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
ddb0: 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
ddc0: 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68 65 20  to *nrow if the 
ddd0: 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20  query is.**     
dde0: 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20       successful 
ddf0: 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  (if the function
de00: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
de10: 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  OK)..**.** {F123
de20: 37 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  76} The [sqlite3
de30: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 75  _get_table()] fu
de40: 6e 63 74 69 6f 6e 20 73 65 74 73 20 69 74 73 20  nction sets its 
de50: 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 0a 2a  *ncolumn value.*
de60: 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
de70: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
de80: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
de90: 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
dea0: 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ry in the.**    
deb0: 20 20 20 20 20 20 73 71 6c 20 70 61 72 61 6d 65        sql parame
dec0: 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f 20  ter, or to zero 
ded0: 69 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 20  if the query in 
dee0: 73 71 6c 20 68 61 73 20 61 6e 20 65 6d 70 74 79  sql has an empty
def0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
df00: 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
df10: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
df20: 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  e(.  sqlite3*,  
df30: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
df40: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
df50: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
df60: 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c  sql,      /* SQL
df70: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
df80: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52   */.  char ***pR
df90: 65 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52  esult,      /* R
dfa0: 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
dfb0: 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72  ery */.  int *nr
dfc0: 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  ow,            /
dfd0: 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
dfe0: 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
dff0: 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  here */.  int *n
e000: 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20  column,         
e010: 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
e020: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
e030: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
e040: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
e050: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
e060: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
e070: 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
e080: 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
e090: 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
e0a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
e0b0: 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
e0c0: 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
e0d0: 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17400}.**.** 
e0e0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
e0f0: 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
e100: 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
e110: 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
e120: 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
e130: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
e140: 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
e150: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
e160: 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
e170: 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
e180: 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
e190: 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
e1a0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
e1b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
e1c0: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
e1d0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
e1e0: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
e1f0: 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
e200: 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
e210: 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20  ite3_free()].   
e220: 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
e230: 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
e240: 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
e250: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
e260: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
e270: 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
e280: 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
e290: 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
e2a0: 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
e2b0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
e2c0: 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
e2d0: 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
e2e0: 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
e2f0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
e300: 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
e310: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
e320: 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
e330: 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
e340: 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
e350: 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
e360: 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
e370: 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
e380: 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
e390: 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
e3a0: 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
e3b0: 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
e3c0: 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
e3d0: 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
e3e0: 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
e3f0: 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
e400: 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
e410: 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
e420: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
e430: 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
e440: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
e450: 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
e460: 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
e470: 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
e480: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
e490: 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
e4a0: 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
e4b0: 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
e4c0: 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
e4d0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
e4e0: 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
e4f0: 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
e500: 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
e510: 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
e520: 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
e530: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
e540: 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
e550: 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
e560: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
e570: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
e580: 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
e590: 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
e5a0: 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
e5b0: 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
e5c0: 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
e5d0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
e5e0: 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
e5f0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
e600: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
e610: 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
e620: 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
e630: 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
e640: 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
e650: 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
e660: 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
e670: 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
e680: 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
e690: 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
e6a0: 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
e6b0: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
e6c0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
e6d0: 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
e6e0: 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
e6f0: 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
e700: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
e710: 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
e720: 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
e730: 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
e740: 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20  he usual printf 
e750: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
e760: 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
e770: 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
e780: 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
e790: 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
e7a0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
e7b0: 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
e7c0: 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
e7d0: 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
e7e0: 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
e7f0: 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
e800: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
e810: 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
e820: 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
e830: 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
e840: 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
e850: 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
e860: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
e870: 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
e880: 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
e890: 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
e8a0: 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
e8b0: 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
e8c0: 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
e8d0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
e8e0: 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
e8f0: 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e  e, so some strin
e900: 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e 74 61  g variable conta
e910: 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
e920: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
e930: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
e940: 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
e950: 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
e960: 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
e970: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
e980: 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
e990: 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
e9a0: 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
e9b0: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
e9c0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
e9d0: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
e9e0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
e9f0: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
ea00: 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
ea10: 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
ea20: 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
ea30: 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
ea40: 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
ea50: 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
ea60: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
ea70: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
ea80: 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
ea90: 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
eaa0: 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
eab0: 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
eac0: 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
ead0: 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
eae0: 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
eaf0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
eb00: 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
eb10: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
eb20: 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
eb30: 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
eb40: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
eb50: 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
eb60: 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
eb70: 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
eb80: 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
eb90: 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
eba0: 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
ebb0: 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
ebc0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
ebd0: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
ebe0: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
ebf0: 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
ec00: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
ec10: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
ec20: 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
ec30: 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
ec40: 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
ec50: 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a  eneral rule you.
ec60: 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  ** should always
ec70: 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
ec80: 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
ec90: 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
eca0: 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65   string .** lite
ecb0: 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
ecc0: 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
ecd0: 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
ece0: 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
ecf0: 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
ed00: 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
ed10: 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
ed20: 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20 70  ng.  Or if the p
ed30: 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
ed40: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74  argument.** list
ed50: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
ed60: 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
ed70: 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
ed80: 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e 67  L" (without sing
ed90: 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e  le.** quotes) in
eda0: 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51   place of the %Q
edb0: 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20   option. {END}  
edc0: 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
edd0: 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
ede0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
edf0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
ee00: 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
ee10: 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
ee20: 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
ee30: 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
ee40: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
ee50: 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
ee60: 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
ee70: 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
ee80: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
ee90: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
eea0: 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
eeb0: 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
eec0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
eed0: 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
eee0: 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
eef0: 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
ef00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
ef10: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25  er..**.** The "%
ef20: 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
ef30: 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74  tion works exact
ef40: 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74  ly like "%s" wit
ef50: 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
ef60: 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
ef70: 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
ef80: 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
ef90: 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
efa0: 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
efb0: 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
efc0: 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
efd0: 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ing. {END}.**.**
efe0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
eff0: 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20 54 68 65  ** {F17403}  The
f000: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
f010: 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  f()] and [sqlite
f020: 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_vmprintf()] in
f030: 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20  terfaces.**     
f040: 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74        return eit
f050: 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  her pointers to 
f060: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
f070: 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65  UTF-8 strings he
f080: 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ld in.**        
f090: 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e     memory obtain
f0a0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
f0b0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55  _malloc()] or NU
f0c0: 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a  LL pointers if.*
f0d0: 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61  *           a ca
f0e0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ll to [sqlite3_m
f0f0: 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a  alloc()] fails..
f100: 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20 20  **.** {F17406}  
f110: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  The [sqlite3_snp
f120: 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
f130: 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f  ce writes a zero
f140: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
f150: 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
f160: 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62  tring into the b
f170: 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  uffer pointed to
f180: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
f190: 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
f1a0: 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74        provided t
f1b0: 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61  hat the first pa
f1c0: 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74  rameter is great
f1d0: 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a  er than zero..**
f1e0: 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20 54 68  .** {F17407}  Th
f1f0: 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  e [sqlite3_snpri
f200: 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
f210: 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 73   does not writes
f220: 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20   slots of.**    
f230: 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70 75         its outpu
f240: 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73 65  t buffer (the se
f250: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20  cond parameter) 
f260: 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e 67  outside the rang
f270: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
f280: 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20  f 0 through N-1 
f290: 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20  (where N is the 
f2a0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 29  first parameter)
f2b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
f2c0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
f2d0: 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
f2e0: 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
f2f0: 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20 74    requested by t
f300: 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66  he format specif
f310: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20 20 0a 2a  ication..**   .*
f320: 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
f330: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
f340: 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
f350: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
f360: 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
f370: 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
f380: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
f390: 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
f3a0: 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
f3b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
f3c0: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
f3d0: 75 62 73 79 73 74 65 6d 20 7b 46 31 37 33 30 30  ubsystem {F17300
f3e0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  }.**.** The SQLi
f3f0: 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68  te core  uses th
f400: 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
f410: 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
f420: 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
f430: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
f440: 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
f450: 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
f460: 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
f470: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
f480: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
f490: 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
f4a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
f4b0: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 56 46 53  e.** windows VFS
f4c0: 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
f4d0: 6c 6f 63 20 61 6e 64 20 66 72 65 65 20 66 6f 72  loc and free for
f4e0: 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
f4f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
f500: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
f510: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
f520: 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
f530: 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
f540: 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
f550: 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
f560: 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
f570: 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ter..** If sqlit
f580: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
f590: 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
f5a0: 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
f5b0: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
f5c0: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
f5d0: 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61  nter.  If the pa
f5e0: 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
f5f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f600: 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
f610: 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
f620: 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
f630: 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
f640: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  nter..**.** Call
f650: 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
f660: 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
f670: 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
f680: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
f690: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
f6a0: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
f6b0: 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
f6c0: 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
f6d0: 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
f6e0: 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  used.  The sqlit
f6f0: 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
f700: 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
f710: 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
f720: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
f730: 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
f740: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
f750: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
f760: 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
f770: 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
f780: 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
f790: 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
f7a0: 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
f7b0: 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
f7c0: 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
f7d0: 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
f7e0: 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
f7f0: 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
f800: 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
f810: 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
f820: 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
f830: 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
f840: 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
f850: 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
f860: 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
f870: 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
f880: 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
f890: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
f8a0: 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
f8b0: 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
f8c0: 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
f8d0: 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a  e3_free()..**.**
f8e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61   The sqlite3_rea
f8f0: 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
f900: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
f910: 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
f920: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f930: 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
f940: 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
f950: 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
f960: 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
f970: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f980: 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
f990: 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
f9a0: 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  * parameter.  If
f9b0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
f9c0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
f9d0: 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
f9e0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
f9f0: 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
fa00: 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
fa10: 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
fa20: 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
fa30: 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
fa40: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
fa50: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
fa60: 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  ()..** If the se
fa70: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
fa80: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
fa90: 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
faa0: 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
fab0: 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
fac0: 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
fad0: 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
fae0: 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
faf0: 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
fb00: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
fb10: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
fb20: 28 29 2e 0a 2a 2a 20 53 71 6c 69 74 65 33 5f 72  ()..** Sqlite3_r
fb30: 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
fb40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
fb50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fb60: 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
fb70: 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
fb80: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
fb90: 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
fba0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
fbb0: 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
fbc0: 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
fbd0: 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
fbe0: 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
fbf0: 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
fc00: 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
fc10: 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
fc20: 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
fc30: 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
fc40: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
fc50: 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
fc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
fc70: 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  reed..** If sqli
fc80: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
fc90: 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
fca0: 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
fcb0: 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
fcc0: 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  freed..**.** The
fcd0: 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
fce0: 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
fcf0: 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
fd00: 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
fd10: 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
fd20: 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
fd30: 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20   byte boundary. 
fd40: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
fd50: 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
fd60: 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
fd70: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fd80: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
fd90: 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  s the malloc(), 
fda0: 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64  realloc().** and
fdb0: 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
fdc0: 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
fdd0: 20 43 20 6c 69 62 72 61 72 79 2e 20 7b 46 31 37   C library. {F17
fde0: 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66  382} However, if
fdf0: 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 63   .** SQLite is c
fe00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
fe10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65   following C pre
fe20: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
fe30: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
fe40: 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  e> SQLITE_MEMORY
fe50: 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
fe60: 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
fe70: 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69 3e 4e 4e  *.** where <i>NN
fe80: 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69 6e 74 65  N</i> is an inte
fe90: 67 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ger, then SQLite
fea0: 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63   create a static
feb0: 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20 61 74 20  .** array of at 
fec0: 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  least <i>NNN</i>
fed0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
fee0: 6e 64 20 75 73 65 20 74 68 61 74 20 61 72 72 61  nd use that arra
fef0: 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  y.** for all of 
ff00: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
ff10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
ff20: 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69  eds. {END}  Addi
ff30: 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79  tional.** memory
ff40: 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f   allocator optio
ff50: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
ff60: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
ff70: 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  es..**.** In SQL
ff80: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
ff90: 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
ffa0: 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
ffb0: 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
ffc0: 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
ffd0: 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
ffe0: 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
fff0: 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
10000 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10010 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
10020 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
10030 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
10040 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
10050 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
10060 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10070 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
10080 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  .** used..**.** 
10090 54 68 65 20 77 69 6e 64 6f 77 73 20 4f 53 20 69  The windows OS i
100a0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
100b0 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
100c0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
100d0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
100e0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
100f0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
10100 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
10110 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
10120 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
10130 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
10140 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
10150 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
10160 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar windows.** in
10170 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
10180 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
10190 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
101a0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
101b0 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
101c0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
101d0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
101e0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
101f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
10200 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  NOMEM]..**.** IN
10210 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
10220 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73  {F17303}  The [s
10230 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
10240 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
10250 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
10260 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20 20 20 20  nter to .**     
10270 20 20 20 20 20 20 6e 65 77 6c 79 20 63 68 65 63        newly chec
10280 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66  ked-out block of
10290 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
102a0 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  s of memory.**  
102b0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
102c0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
102d0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f   .**           o
102e0 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  r it returns NUL
102f0 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c  L if it is unabl
10300 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65  e to fulfill the
10310 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20   request..**.** 
10320 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73  {F17304}  The [s
10330 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
10340 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
10350 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
10360 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  er if.**        
10370 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61     N is less tha
10380 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
10390 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  ro..**.** {F1730
103a0 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  5}  The [sqlite3
103b0 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66  _free(P)] interf
103c0 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d  ace releases mem
103d0 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  ory previously.*
103e0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
103f0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
10400 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
10410 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10420 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
10430 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69    making it avai
10440 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e  lable for reuse.
10450 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36 7d 20  .**.** {F17306} 
10460 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
10470 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20  te3_free(NULL)] 
10480 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
10490 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  -op..**.** {F173
104a0 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  10}  A call to [
104b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
104c0 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c  0,N)] is equival
104d0 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a  ent to a call.**
104e0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73             to [s
104f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
10500 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 32  ]..**.** {F17312
10510 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
10520 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
10530 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e  0)] is equivalen
10540 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20  t to a call.**  
10550 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c           to [sql
10560 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a  ite3_free(P)]..*
10570 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20 20 54  *.** {F17315}  T
10580 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
10590 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ses [sqlite3_mal
105a0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
105b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
105c0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73            and [s
105d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66  qlite3_free()] f
105e0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65  or all of its me
105f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10600 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
10610 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65   deallocation ne
10620 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  eds..**.** {F173
10630 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  18}  The [sqlite
10640 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
10650 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
10660 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74  s either a point
10670 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
10680 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68  to a block of ch
10690 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79  ecked-out memory
106a0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
106b0 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20  ytes in size.** 
106c0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
106d0 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
106e0 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  , or a NULL poin
106f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ter..**.** {F173
10700 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  21}  When [sqlit
10710 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
10720 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e   returns a non-N
10730 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20  ULL pointer, it 
10740 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
10750 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69     copies the fi
10760 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63  rst K bytes of c
10770 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e  ontent from P in
10780 74 6f 20 74 68 65 20 6e 65 77 6c 79 20 61 6c 6c  to the newly all
10790 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  ocated.**       
107a0 20 20 20 20 77 68 65 72 65 20 4b 20 69 73 20 74      where K is t
107b0 68 65 20 6c 65 73 73 6f 72 20 6f 66 20 4e 20 61  he lessor of N a
107c0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
107d0 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  he buffer P..**.
107e0 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20 57 68 65  ** {F17322}  Whe
107f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
10800 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
10810 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
10820 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
10830 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65 61             relea
10840 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20 50  ses the buffer P
10850 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 33 7d  ..**.** {F17323}
10860 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
10870 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
10880 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20  turns NULL, the 
10890 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20 20  buffer P is.**  
108a0 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64           not mod
108b0 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73 65  ified or release
108c0 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  d..**.** LIMITAT
108d0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 37  IONS:.**.** {U17
108e0 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74 65  350}  The pointe
108f0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
10900 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
10910 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
10920 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  lloc()].**      
10930 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69 74       must be eit
10940 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
10950 20 61 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69   a pointer obtai
10960 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
10970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e  .**           in
10980 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
10990 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
109a0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
109b0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 73 0a 2a  oc()] that has.*
109c0 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
109d0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
109e0 2a 0a 2a 2a 20 7b 55 31 37 33 35 31 7d 20 20 54  *.** {U17351}  T
109f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
10a00 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
10a10 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
10a20 66 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  f .**           
10a30 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
10a40 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
10a50 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
10a60 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
10a70 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10a80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
10a90 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 76  lloc()]..**.*/.v
10aa0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
10ab0 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
10ac0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10ad0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
10ae0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
10af0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
10b00 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
10b10 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
10b20 69 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a 2a 0a  ics {F17370}.**.
10b30 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
10b40 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
10b50 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
10b60 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
10b70 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
10b80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10b90 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
10ba0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
10bb0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 74  _realloc()].** t
10bc0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10bd0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 69  tion subsystem i
10be0 6e 63 6c 75 64 65 64 20 77 69 74 68 69 6e 20 74  ncluded within t
10bf0 68 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  he SQLite..**.**
10c00 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
10c10 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 65 20  ** {F17371} The 
10c20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
10c30 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
10c40 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
10c50 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
10c60 66 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  f bytes of memor
10c70 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
10c80 74 61 6e 64 69 6e 67 20 0a 2a 2a 20 20 20 20 20  tanding .**     
10c90 20 20 20 20 20 28 6d 61 6c 6c 6f 63 65 64 20 62       (malloced b
10ca0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
10cb0 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54 68  *.** {F17373} Th
10cc0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
10cd0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
10ce0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
10cf0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20  he maximum.**   
10d00 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
10d10 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
10d20 75 73 65 64 28 29 5d 20 0a 2a 2a 20 20 20 20 20  used()] .**     
10d30 20 20 20 20 20 73 69 6e 63 65 20 74 68 65 20 68       since the h
10d40 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 77 61  ighwater mark wa
10d50 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a  s last reset..**
10d60 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20 54 68 65  .** {F17374} The
10d70 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
10d80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
10d90 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
10da0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10db0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
10dc0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
10dd0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
10de0 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64 20            added 
10df0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
10e00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10e10 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
10e20 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
10e30 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68     but not overh
10e40 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
10e50 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
10e60 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
10e70 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69  *          routi
10e80 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
10e90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
10ea0 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  call..** .** {F1
10eb0 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79  7375} The memory
10ec0 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20   highwater mark 
10ed0 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
10ee0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
10ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
10f00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
10f10 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
10f20 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
10f30 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
10f40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10f50 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
10f60 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75   true.  The valu
10f70 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
10f80 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
10f90 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
10fa0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
10fb0 69 67 68 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  ighwater mark.**
10fc0 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72 20            prior 
10fd0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
10fe0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
10ff0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
11000 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
11010 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
11020 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
11030 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
11040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11050 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
11060 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
11070 20 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20   {F17390}.**.** 
11080 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
11090 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
110a0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
110b0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
110c0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
110d0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f  select random RO
110e0 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74  WIDs when insert
110f0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
11100 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
11110 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
11120 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
11130 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54  ssible ROWID.  T
11140 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
11150 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
11160 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
11170 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
11180 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
11190 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
111a0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
111b0 69 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  iations to acces
111c0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
111d0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
111e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
111f0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
11200 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
11210 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
11220 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
11230 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
11240 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
11250 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
11260 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
11270 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
11280 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
11290 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
112a0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
112b0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
112c0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
112d0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
112e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
112f0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
11300 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
11310 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
11320 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
11330 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
11340 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
11350 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
11360 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11370 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
11380 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
11390 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
113a0 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68 65  .** {F17392} The
113b0 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d   [sqlite3_random
113c0 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72  ness(N,P)] inter
113d0 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79  face writes N by
113e0 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
113f0 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20     high-quality 
11400 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
11410 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
11420 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
11430 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
11440 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
11450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11460 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
11470 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
11480 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a  ks {F12500}.**.*
11490 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
114a0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
114b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
114c0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
114d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
114e0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
114f0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
11500 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
11510 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
11520 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
11530 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
11540 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
11550 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
11560 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
11570 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
11580 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11590 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
115a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
115b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
115c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
115d0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
115e0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
115f0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
11600 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
11610 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
11620 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
11630 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
11640 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
11650 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
11660 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
11670 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
11680 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
11690 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
116a0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
116b0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
116c0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
116d0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
116e0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
116f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
11700 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
11710 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
11720 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
11730 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
11740 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
11750 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
11760 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
11770 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
11780 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
11790 72 72 6f 72 2e 20 20 20 49 66 20 74 68 65 20 61  rror.   If the a
117a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
117b0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
117c0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
117d0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
117e0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
117f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
11800 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ].** then [sqlit
11810 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
11820 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
11830 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
11840 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
11850 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
11860 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
11870 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
11880 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
11890 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
118a0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
118b0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
118c0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
118d0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
118e0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
118f0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
11900 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11910 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
11920 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
11930 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
11940 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
11950 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
11960 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
11970 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
11980 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
11990 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
119a0 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  zer code is [SQL
119b0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
119c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
119d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
119e0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
119f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
11a00 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
11a10 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
11a20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
11a30 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
11a40 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
11a50 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
11a60 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
11a70 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
11a80 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
11a90 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
11aa0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
11ab0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
11ac0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
11ad0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
11ae0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
11af0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
11b00 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  f a table..**.**
11b10 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
11b20 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
11b30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
11b40 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
11b50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
11b60 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
11b70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
11b80 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
11b90 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
11ba0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
11bb0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
11bc0 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  eger .** [SQLITE
11bd0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
11be0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
11bf0 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c  ies the particul
11c00 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20  ar action.** to 
11c10 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54  be authorized. T
11c20 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
11c30 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65   sixth.** parame
11c40 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
11c50 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
11c60 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
11c70 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a   that contain .*
11c80 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74  * additional det
11c90 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
11ca0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
11cb0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
11cc0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
11cd0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
11ce0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
11cf0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
11d00 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
11d10 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f   untrusted.** so
11d20 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
11d30 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
11d40 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74  tements do not t
11d50 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
11d60 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61  a.** that they a
11d70 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
11d80 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
11d90 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  hey do not try t
11da0 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c  o.** execute mal
11db0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
11dc0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
11dd0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
11de0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
11df0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
11e00 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
11e10 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
11e20 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
11e30 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
11e40 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
11e50 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
11e60 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
11e70 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
11e80 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
11e90 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
11ea0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
11eb0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
11ec0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
11ed0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
11ee0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
11ef0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
11f00 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
11f10 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
11f20 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
11f30 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
11f40 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
11f50 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
11f60 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
11f70 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
11f80 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
11f90 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
11fa0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
11fb0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
11fc0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
11fd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
11fe0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
11ff0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
12000 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
12010 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
12020 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
12030 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
12040 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
12050 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
12060 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
12070 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
12080 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
12090 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
120a0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
120b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
120c0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
120d0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
120e0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
120f0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
12100 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
12110 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
12120 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
12130 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
12140 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
12150 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
12160 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
12170 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
12180 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b  nly during .** [
12190 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
121a0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
121b0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
121c0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
121d0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
121e0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
121f0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
12200 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  tep()]..**.** IN
12210 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
12220 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b 73 71  {F12501} The [sq
12230 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
12240 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  izer(D,...)] int
12250 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
12260 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   a.**          a
12270 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
12280 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ck with database
12290 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
122a0 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54 68  *.** {F12502} Th
122b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
122c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
122d0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
122e0 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ts are.**       
122f0 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65     being compile
12300 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d  d.**.** {F12503}
12310 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
12320 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
12330 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  rns any value ot
12340 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
12350 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
12360 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
12370 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
12380 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  NY] then.**     
12390 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
123a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
123b0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
123c0 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ll that caused.*
123d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
123e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
123f0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
12400 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20  fail with an.** 
12410 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
12420 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
12430 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  de and an approp
12440 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
12450 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  age..**.** {F125
12460 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  04} When the aut
12470 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12480 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
12490 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74  _OK], the operat
124a0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
124b0 64 65 73 63 72 69 62 65 64 20 69 73 20 63 6f 64  described is cod
124c0 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a  ed normally..**.
124d0 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68 65 6e  ** {F12505} When
124e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
124f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12500 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
12510 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12520 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
12530 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
12540 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
12550 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20  aused the.**    
12560 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
12570 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
12580 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20   shall fail.**  
12590 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20          with an 
125a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
125b0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
125c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
125d0 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61  *          expla
125e0 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73  ining that acces
125f0 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a  s is denied..**.
12600 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66 20 74  ** {F12506} If t
12610 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
12620 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
12630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
12640 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
12650 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
12660 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
12670 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  nd the authorize
12680 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
12690 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
126a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
126b0 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
126c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
126d0 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20  nstructed to.** 
126e0 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
126f0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
12700 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
12710 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
12720 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20  ould have.**    
12730 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20        been read 
12740 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
12750 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
12760 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 37 7d  ..**.** {F12507}
12770 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
12780 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
12790 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
127a0 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
127b0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
127c0 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f  k) is anything o
127d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
127e0 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a  E_READ], then.**
127f0 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
12800 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
12810 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
12820 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
12830 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 0a  LITE_DENY]. .**.
12840 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 65 20  ** {F12510} The 
12850 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12860 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
12870 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
12880 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
12890 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61      the third pa
128a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
128b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
128c0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
128d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ace..**.** {F125
128e0 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  11} The second p
128f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
12900 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
12910 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20 20 20 20  nteger .**      
12920 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
12930 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
12940 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
12950 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
12960 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
12970 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
12980 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 32  d..**.** {F12512
12990 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  } The third thro
129a0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
129b0 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
129c0 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20  back are.**     
129d0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
129e0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
129f0 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 20 20  t contain .**   
12a00 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61         additiona
12a10 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
12a20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
12a30 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
12a40 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63 68  ** {F12520} Each
12a50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
12a60 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12a70 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68  ()] overrides th
12a80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  e.**          an
12a90 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73  y previously ins
12aa0 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65  talled authorize
12ab0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 31  r..**.** {F12521
12ac0 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69  } A NULL authori
12ad0 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
12ae0 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
12af0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
12b00 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
12b10 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d 20  .**.** {F12522} 
12b20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
12b30 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
12b40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
12b50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
12b60 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
12b70 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
12b80 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
12b90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
12ba0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
12bb0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
12bc0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
12bd0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
12be0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
12bf0 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a  des {F12590}.**.
12c00 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
12c10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
12c20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
12c30 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
12c40 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
12c50 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
12c60 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
12c70 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
12c80 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
12c90 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
12ca0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
12cb0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
12cc0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
12cd0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12ce0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
12cf0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
12d00 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
12d10 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
12d20 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
12d30 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
12d40 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
12d50 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
12d60 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
12d70 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
12d80 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
12d90 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
12da0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
12db0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
12dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
12dd0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
12de0 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a 2a  odes {F12550}.**
12df0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
12e00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
12e10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
12e20 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
12e30 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
12e40 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
12e50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74   authorizer cert
12e60 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
12e70 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
12e80 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
12e90 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
12ea0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
12eb0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
12ec0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
12ed0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
12ee0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
12ef0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
12f00 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
12f10 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
12f20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
12f30 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
12f40 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
12f50 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
12f60 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
12f70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
12f80 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   be .** authoriz
12f90 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
12fa0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
12fb0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
12fc0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
12fd0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
12fe0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
12ff0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
13000 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
13010 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
13020 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
13030 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
13040 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
13050 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
13060 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
13070 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
13080 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
13090 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63   "temp", .** etc
130a0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
130b0 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
130c0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
130d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
130e0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
130f0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
13100 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
13110 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
13120 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
13130 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
13140 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
13150 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
13160 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a   directly from .
13170 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
13180 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   code..**.** INV
13190 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
131a0 46 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f  F12551} The seco
131b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
131c0 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  an .**          
131d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
131e0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
131f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
13200 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67   always an integ
13210 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
13220 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
13230 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
13240 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
13250 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  at action.**    
13260 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61        is being a
13270 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
13280 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20 33 72   {F12552} The 3r
13290 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
132a0 74 65 72 73 20 74 6f 20 74 68 65 20 0a 2a 2a 20  ters to the .** 
132b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
132c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
132d0 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e   | authorization
132e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
132f0 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on].**          
13300 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
13310 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
13320 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 0a 2a  ding on which .*
13330 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
13340 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72  TE_COPY | author
13350 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73  izer code] is us
13360 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
13370 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
13380 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65 20 35  * {F12553} The 5
13390 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
133a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
133b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
133c0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
133d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
133e0 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
133f0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64 61         of the da
13400 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a  tabase (example:
13410 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
13420 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
13430 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  able..**.** {F12
13440 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72  554} The 6th par
13450 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
13460 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13470 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
13480 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
13490 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20  allback] is the 
134a0 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
134b0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
134c0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
134d0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
134e0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20  nsible for.**   
134f0 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65 73         the acces
13500 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
13510 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
13520 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
13530 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 20 20  ctly from .**   
13540 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c         top-level
13550 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
13560 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13570 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13580 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
13590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
135a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
135b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
135c0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
135d0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
135e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
135f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
13600 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
13610 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
13620 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
13630 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
13640 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13650 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
13660 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
13670 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
13680 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
13690 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
136a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
136b0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
136c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
136d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
136e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
136f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
13700 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
13710 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
13720 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
13730 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13740 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
13750 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
13760 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
13770 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13780 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13790 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
137a0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
137b0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
137c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
137d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
137e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
137f0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
13800 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
13810 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13820 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13830 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
13840 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
13850 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13860 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13870 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13880 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
13890 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
138a0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
138b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
138c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
138d0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
138e0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
138f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
13900 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13920 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
13930 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
13940 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
13950 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
13960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13970 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
13980 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
13990 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
139a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
139b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
139c0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
139d0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
139e0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
139f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
13a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
13a10 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
13a20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
13a30 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
13a40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13a50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
13a60 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
13a70 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
13a80 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
13a90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
13aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
13ab0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
13ac0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
13ad0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
13ae0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13af0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
13b00 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
13b10 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
13b20 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
13b30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13b40 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
13b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
13b60 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
13b70 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
13b80 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
13b90 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
13ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
13bb0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
13bc0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
13bd0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
13be0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
13bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
13c00 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
13c10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13c20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13c30 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
13c40 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
13c50 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
13c60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13c70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13c80 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
13c90 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
13ca0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13cb0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
13cc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13cd0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
13ce0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
13cf0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
13d00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13d10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13d20 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
13d30 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
13d40 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
13d50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13d60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13d70 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
13d80 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
13d90 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
13da0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13dc0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
13dd0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
13de0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
13df0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13e00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13e10 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
13e20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
13e30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
13e40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13e60 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
13e70 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
13e80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
13e90 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
13ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13eb0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
13ec0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
13ed0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
13ee0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
13ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
13f00 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
13f10 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74     31   /* Funct
13f20 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ion Name   NULL 
13f30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
13f50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
13f60 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
13f70 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
13f80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
13f90 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
13fa0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  ng Functions {F1
13fb0 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2280}.**.** Thes
13fc0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
13fd0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
13fe0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
13ff0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
14000 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
14010 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
14020 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
14030 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
14040 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
14050 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
14060 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
14070 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
14080 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
14090 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
140a0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
140b0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
140c0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
140d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
140e0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
140f0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
14100 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
14110 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
14120 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
14130 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
14140 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
14150 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
14160 69 67 67 65 72 73 75 62 70 72 6f 67 72 61 6d 20  iggersubprogram 
14170 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
14180 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
14190 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
141a0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
141b0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
141c0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
141d0 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 63  er..** .** The c
141e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
141f0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
14200 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
14210 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
14220 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
14230 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
14240 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
14250 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
14260 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
14270 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
14280 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
14290 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
142a0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
142b0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
142c0 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
142d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f   The sqlite3_pro
142e0 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75  file() API is cu
142f0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
14300 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
14310 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63  and.** is subjec
14320 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  t to change or r
14330 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75  emoval in a futu
14340 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a  re release..**.*
14350 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 72 65  * The trigger re
14360 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65 20  porting feature 
14370 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  of the trace cal
14380 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65  lback is conside
14390 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  red.** experimen
143a0 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
143b0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ct to change or 
143c0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
143d0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46  e releases..** F
143e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
143f0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  f SQLite might a
14400 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63  lso add new trac
14410 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69  e callback .** i
14420 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  nvocations..**.*
14430 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
14440 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65  .** {F12281} The
14450 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
14460 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
14470 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
14480 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
14490 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51    whenever an SQ
144a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  L statement firs
144b0 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63  t begins to exec
144c0 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ute and.**      
144d0 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20 74      whenever a t
144e0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
144f0 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  m first begins t
14500 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  o run..**.** {F1
14510 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20  2282} Each call 
14520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
14530 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  e()] overrides t
14540 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  he previously.**
14550 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
14560 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62  ered trace callb
14570 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ack..**.** {F122
14580 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65  83} A NULL trace
14590 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c   callback disabl
145a0 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a  es tracing..**.*
145b0 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20 66  * {F12284} The f
145c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
145d0 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
145e0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
145f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14600 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
14610 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  as the 3rd argum
14620 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
14630 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  trace()]..**.** 
14640 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73 65 63  {F12285} The sec
14650 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
14660 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
14670 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  ck is a.**      
14680 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
14690 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67 20  ted UTF8 string 
146a0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f  containing the o
146b0 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20  riginal text.** 
146c0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
146d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
146e0 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69   it was passed i
146f0 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nto [sqlite3_pre
14700 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20  pare_v2()].**   
14710 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71         or the eq
14720 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20  uivalent, or an 
14730 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69  SQL comment indi
14740 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e  cating the begin
14750 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
14760 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75   of a trigger su
14770 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20  bprogram..**.** 
14780 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c  {F12287} The cal
14790 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
147a0 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
147b0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
147c0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
147d0 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20          as each 
147e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
147f0 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nishes..**.** {F
14800 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74  12288} The first
14810 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
14820 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
14830 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
14840 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
14850 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
14860 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
14870 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
14880 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  289} The second 
14890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
148a0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
148b0 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  k is a.**       
148c0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
148d0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
148e0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  that contains th
148f0 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20  e complete text 
14900 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
14910 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14920 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65   as it was proce
14930 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ssed by [sqlite3
14940 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
14950 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
14960 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a  e equivalent..**
14970 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68 65  .** {F12290} The
14980 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14990 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
149a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
149b0 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20  estimate.**     
149c0 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62       of the numb
149d0 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
149e0 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  s of wall-clock 
149f0 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f  time required to
14a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e  .**          run
14a10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14a20 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f  nt from start to
14a30 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64   finish..*/.void
14a40 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
14a50 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
14a60 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
14a70 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
14a80 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
14a90 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
14aa0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
14ab0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
14ac0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
14ad0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
14ae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14af0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
14b00 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  s Callbacks {F12
14b10 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  910}.**.** This 
14b20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
14b30 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
14b40 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
14b50 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
14b60 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
14b70 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
14b80 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
14b90 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
14ba0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
14bb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
14bc0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
14bd0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
14be0 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  .   An example u
14bf0 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
14c00 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
14c10 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
14c20 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
14c30 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  e query..**.** I
14c40 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
14c50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
14c60 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
14c70 65 72 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ertion is.** int
14c80 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
14c90 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
14ca0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
14cb0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
14cc0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64  utton on a GUI d
14cd0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
14ce0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
14cf0 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65 20  ** {F12911} The 
14d00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
14d10 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
14d20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
14d30 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20  s_handler()].** 
14d40 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
14d50 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
14d60 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
14d70 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
14d80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14d90 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
14da0 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20 70  * {F12912} The p
14db0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
14dc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
14dd0 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72   for every N vir
14de0 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tual.**         
14df0 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
14e00 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
14e10 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14e20 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
14e30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
14e40 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
14e50 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69  ] call that regi
14e60 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
14e70 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e     the callback.
14e80 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69 66 20    <todo>What if 
14e90 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  N is less than 1
14ea0 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
14eb0 46 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67  F12913} The prog
14ec0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74  ress callback it
14ed0 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69  self is identifi
14ee0 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a  ed by the third.
14ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
14f00 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
14f10 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
14f20 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  r()]..**.** {F12
14f30 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20  914} The fourth 
14f40 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69 74 65  argument [sqlite
14f50 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
14f60 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a 20 20  er()] is a.***  
14f70 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e         void poin
14f80 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
14f90 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14fa0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
14fb0 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69  function each ti
14fc0 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  me it is invoked
14fd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d  ..**.** {F12915}
14fe0 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
14ff0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
15000 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20  esults in fewer 
15010 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
15020 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67   N opcodes being
15030 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 20 20   executed,.**   
15040 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
15050 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
15060 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b  k is never invok
15070 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a  ed. {END}.** .**
15080 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72 79 20   {F12916} Every 
15090 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
150a0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
150b0 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  r()].**         
150c0 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 20   overwrites any 
150d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
150e0 74 65 72 65 20 70 72 6f 67 72 65 73 73 20 68 61  tere progress ha
150f0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ndler..**.** {F1
15100 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f  2917} If the pro
15110 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
15120 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74  llback is NULL t
15130 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a  hen no progress.
15140 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
15150 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  ler is invoked..
15160 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49  **.** {F12918} I
15170 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
15180 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15190 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74  a result other t
151a0 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20  han 0, then.**  
151b0 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61          the beha
151c0 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71  vior is a if [sq
151d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
151e0 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c  )] had been call
151f0 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
15200 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
15210 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
15220 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
15230 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
15240 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
15250 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
15260 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46  se Connection {F
15270 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12700}.**.** The
15280 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
15290 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
152a0 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
152b0 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20  ame.** is given 
152c0 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  by the filename 
152d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
152e0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
152f0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
15300 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66 6f  d as UTF-8.** fo
15310 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
15320 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
15330 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
15340 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20 74  s UTF-16.** in t
15350 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
15360 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
15370 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
15380 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  An [sqlite3*] ha
15390 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 20  ndle is usually 
153a0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
153b0 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e  b, even.** if an
153c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
153d0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
153e0 6f 6e 20 69 73 20 69 66 20 53 51 4c 69 74 65 20  on is if SQLite 
153f0 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f 20  is unable.** to 
15400 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
15410 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
15420 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61 20  ite3] object, a 
15430 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  NULL will.** be 
15440 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
15450 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
15460 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
15470 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
15480 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
15490 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
154a0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 0a 2a  nd/or created).*
154b0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  * successfully, 
154c0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  then [SQLITE_OK]
154d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
154e0 74 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a 20 65  therwise an.** e
154f0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
15500 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b  urned.  The.** [
15510 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
15520 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
15530 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69  rmsg16()]  routi
15540 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
15550 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
15560 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
15570 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
15580 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
15590 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63   The default enc
155a0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
155b0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
155c0 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69  TF-8 if.** [sqli
155d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
155e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
155f0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  )] is called and
15600 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
15610 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
15620 64 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  der if [sqlite3_
15630 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
15640 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
15650 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
15660 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
15670 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
15680 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
15690 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ed with the [sql
156a0 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68  ite3*] handle sh
156b0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
156c0 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a 2a   by passing it.*
156d0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  * to [sqlite3_cl
156e0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
156f0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
15700 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
15710 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
15720 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
15730 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  rks like [sqlite
15740 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20 65 78  3_open()] .** ex
15750 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
15760 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
15770 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
15780 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
15790 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
157a0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
157b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
157c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
157d0 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20 6f   can be.** one o
157e0 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  f:.**.** <ol>.**
157f0 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
15800 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a  PEN_READONLY].**
15810 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
15820 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a  PEN_READWRITE].*
15830 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
15840 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
15850 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
15860 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  REATE].** </ol>.
15870 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
15880 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20  value opens the 
15890 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e  database read-on
158a0 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20 64  ly. .** If the d
158b0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
158c0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
158d0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
158e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
158f0 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70  second option op
15900 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ens.** the datab
15910 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
15920 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
15930 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
15940 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69  ing only if.** i
15950 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
15960 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20 20  ite protected.  
15970 49 6e 20 65 69 74 68 65 72 20 63 61 73 65 20 74  In either case t
15980 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 6d  he database.** m
15990 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
159a0 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73  t or an error is
159b0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
159c0 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20  third option.** 
159d0 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
159e0 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
159f0 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63  nd writing and c
15a00 72 65 61 74 65 73 20 69 74 20 69 66 20 69 74 20  reates it if it 
15a10 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65  does.** not alre
15a20 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68  ady exist..** Th
15a30 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20  e third options 
15a40 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  is behavior that
15a50 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
15a60 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
15a70 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
15a80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
15a90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
15aa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
15ab0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15ac0 5d 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ] is not one of 
15ad0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
15ae0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
15af0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
15b00 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
15b10 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
15b20 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
15b30 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69  y:", then an pri
15b40 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72  vate.** in-memor
15b50 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
15b60 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
15b70 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nnection.  This 
15b80 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74  in-memory.** dat
15b90 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
15ba0 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  h when the datab
15bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
15bc0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
15bd0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
15be0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b  SQLite might mak
15bf0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
15c00 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
15c10 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65  names.** that be
15c20 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
15c30 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20   character.  It 
15c40 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
15c50 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64  hat .** when a d
15c60 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
15c70 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67   really does beg
15c80 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74  in with.** ":" t
15c90 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74  hat you prefix t
15ca0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
15cb0 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65   a pathname like
15cc0 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69   "./" to.** avoi
15cd0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
15ce0 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
15cf0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
15d00 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
15d10 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a  ivate temporary.
15d20 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
15d30 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
15d40 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61  ted.  This priva
15d50 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
15d60 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
15d70 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
15d80 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
15d90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15da0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
15db0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
15dc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
15dd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
15de0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
15df0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
15e00 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
15e10 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
15e20 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65   system .** inte
15e30 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20 6e  rface that the n
15e40 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
15e50 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
15e60 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  e.  If the.** fo
15e70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15e80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15e90 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
15ea0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a  t [sqlite3_vfs].
15eb0 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  ** object is use
15ec0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
15ed0 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72   to windows user
15ee0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
15ef0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
15f00 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
15f10 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74  ent.** of [sqlit
15f20 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
15f30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
15f40 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  )] must be UTF-8
15f50 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
15f60 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
15f70 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
15f80 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
15f90 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
15fa0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
15fb0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
15fc0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
15fd0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
15fe0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  hem into.** [sql
15ff0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
16000 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16010 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
16020 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
16030 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2701} The [sqlit
16040 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
16050 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
16060 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
16070 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16080 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63  ()] interfaces c
16090 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20  reate a new.**  
160a0 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
160b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
160c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
160d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61            the da
160e0 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65  tabase file give
160f0 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74  n in their first
16100 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
16110 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66  * {F12702} The f
16120 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
16130 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
16140 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  as UTF-8.**     
16150 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65       for [sqlite
16160 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
16170 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16180 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a  ] and as UTF-16.
16190 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
161a0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
161b0 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
161c0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
161d0 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75  ** {F12703} A su
161e0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
161f0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
16200 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
16210 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a 2a 2a  3_open16()], .**
16220 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
16230 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
16240 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65   writes a pointe
16250 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20  r to a new.**   
16260 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
16270 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74   connection] int
16280 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b  o *ppDb..**.** {
16290 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c  F12704} The [sql
162a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
162b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
162c0 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  , and.**        
162d0 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
162e0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
162f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
16300 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73  OK] upon success
16310 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
16320 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
16330 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20  [error code] on 
16340 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
16350 46 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61  F12706} The defa
16360 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ult text encodin
16370 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61  g for a new data
16380 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
16390 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
163a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
163b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
163c0 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55  _v2()] will be U
163d0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  TF-8..**.** {F12
163e0 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74  707} The default
163f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
16400 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
16410 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
16420 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16430 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77  ite3_open16()] w
16440 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a  ill be UTF-16..*
16450 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68  *.** {F12709} Th
16460 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
16470 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,D)] interface 
16480 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
16490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
164a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
164b0 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68  D,G,0)] where th
164c0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73  e G parameter is
164d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
164e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
164f0 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45  ITE]|[SQLITE_OPE
16500 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a  N_CREATE]..**.**
16510 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68 65   {F12711} If the
16520 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
16530 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16540 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
16550 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
16560 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
16570 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
16580 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61  NLY] then the da
16590 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
165a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
165b0 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a   reading only..*
165c0 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66  *.** {F12712} If
165d0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
165e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
165f0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
16600 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
16610 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
16620 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
16630 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74  EADWRITE] then t
16640 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
16650 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
16660 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72    reading and wr
16670 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
16680 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e  e, or for readin
16690 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a  g only if the.**
166a0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69            file i
166b0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
166c0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
166d0 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  ng system..**.**
166e0 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68 65   {F12713} If the
166f0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
16700 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
16710 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73  (F,D,G,V)] omits
16720 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
16730 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
16740 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
16750 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
16760 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
16770 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79        previously
16780 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
16790 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
167a0 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66 20  .** {F12714} If 
167b0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
167c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
167d0 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  (v2(F,D,G,V)] co
167e0 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
167f0 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
16800 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
16810 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61  EATE] and the da
16820 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
16830 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76  **          prev
16840 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68  iously exist, th
16850 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  en an attempt is
16860 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20   made to create 
16870 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
16880 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64  initialize the d
16890 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  atabase..**.** {
168a0 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66  F12717} If the f
168b0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
168c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
168d0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
168e0 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
168f0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
16900 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
16910 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
16920 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20   an private,.** 
16930 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72           ephemer
16940 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  al, in-memory da
16950 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65  tabase is create
16960 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
16970 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20  tion..**        
16980 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
16990 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
169a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
169b0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
169c0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
169d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
169e0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  todo>.**.** {F12
169f0 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65  719} If the file
16a00 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20  name is NULL or 
16a10 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
16a20 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
16a30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
16a40 65 72 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20  ermeral on-disk 
16a50 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
16a60 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20   created..**    
16a70 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
16a80 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
16a90 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
16aa0 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
16ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
16ac0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16ad0 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
16ae0 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61  {F12721} The [da
16af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16b00 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a  n] created by .*
16b10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16b20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
16b30 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74  G,V)] will use t
16b40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
16b50 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
16b60 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62  ect identified b
16b70 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65  y the V paramete
16b80 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  r, or.**        
16b90 20 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73    the default [s
16ba0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
16bb0 63 74 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c  ct is V is a NUL
16bc0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e  L pointer..*/.in
16bd0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
16be0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
16bf0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
16c00 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
16c10 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
16c20 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
16c30 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
16c40 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
16c50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
16c60 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
16c70 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
16c80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
16c90 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
16ca0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
16cb0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
16cc0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
16cd0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
16ce0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
16cf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
16d00 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
16d10 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
16d20 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
16d30 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
16d40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
16d50 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
16d60 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
16d70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
16d80 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
16d90 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
16da0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
16db0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
16dc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16dd0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
16de0 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31  And Messages {F1
16df0 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2800}.**.** The 
16e00 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16e10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
16e20 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
16e30 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
16e40 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
16e50 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
16e60 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
16e70 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f  sult code].** fo
16e80 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
16e90 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
16ea0 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
16eb0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b  ciated.** with [
16ec0 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20  sqlite3] handle 
16ed0 27 64 62 27 2e 20 49 66 20 61 20 70 72 69 6f 72  'db'. If a prior
16ee0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
16ef0 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74   but the.** most
16f00 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
16f10 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
16f20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
16f30 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
16f40 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  e().** is undefi
16f50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
16f60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
16f70 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
16f80 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
16f90 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
16fa0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
16fb0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
16fc0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
16fd0 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
16fe0 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  ively..** Memory
16ff0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
17000 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
17010 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
17020 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
17030 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
17040 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
17050 72 79 20 77 69 74 68 20 66 72 65 65 69 6e 67 20  ry with freeing 
17060 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
17070 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
17080 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
17090 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
170a0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
170b0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
170c0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
170d0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
170e0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  nctions..**.** I
170f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
17100 20 7b 46 31 32 38 30 31 7d 20 54 68 65 20 5b 73   {F12801} The [s
17110 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
17120 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
17130 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
17140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
17150 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
17160 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 20 20 20   code] or.**    
17170 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f        [SQLITE_IO
17180 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
17190 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
171a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
171b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
171c0 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66  ly failed interf
171d0 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  ace call associa
171e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
171f0 77 69 74 68 20 5b 64 61 74 61 62 61 73 65 20 63  with [database c
17200 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
17210 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54 68 65  .** {F12803} The
17220 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
17230 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (D)] and [sqlite
17240 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a  3_errmsg16(D)].*
17250 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
17260 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67  faces return Eng
17270 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
17280 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
17290 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
172a0 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d  e error in the m
172b0 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66  ostly recently f
172c0 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
172d0 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20  call,.**        
172e0 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74    encoded as eit
172f0 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31  her UTF8 or UTF1
17300 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
17310 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37 7d 20 54  **.** {F12807} T
17320 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
17330 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
17340 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
17350 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
17360 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
17370 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
17380 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69  he next SQLite i
17390 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a  nterface call..*
173a0 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d 20 43 61  *.** {F12808} Ca
173b0 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69  lls to API routi
173c0 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  nes that do not 
173d0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
173e0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
173f0 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69   (example: [sqli
17400 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
17410 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20  ]) do not.**    
17420 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65        change the
17430 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d   error code or m
17440 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20  essage returned 
17450 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
17460 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
17470 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
17480 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
17490 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
174a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 39 7d 20  .**.** {F12809} 
174b0 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20  Interfaces that 
174c0 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74  are not associat
174d0 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66  ed with a specif
174e0 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ic.**          [
174f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17500 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a  ion] (examples:.
17510 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
17520 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
17530 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  or [sqlite3_enab
17540 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
17550 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  )].**          d
17560 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  o not change the
17570 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
17580 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
17590 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
175a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72  ()], [sqlite3_er
175b0 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  rmsg()], or [sql
175c0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
175d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
175e0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
175f0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
17600 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
17610 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
17620 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
17630 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
17640 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17650 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
17660 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30  ent Object {F130
17670 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
17680 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
17690 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
176a0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
176b0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
176c0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
176d0 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51  resent single SQ
176e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54  L statements.  T
176f0 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  his.** object is
17700 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
17710 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
17720 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20  statement" or a 
17730 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
17740 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
17750 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
17760 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20  tement"..** .** 
17770 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
17780 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
17790 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
177a0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
177b0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
177c0 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
177d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
177e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
177f0 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
17800 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
17810 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
17820 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
17830 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
17840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
17850 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
17860 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a  _* interfaces]..
17870 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
17880 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
17890 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
178a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
178b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
178c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
178d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
178e0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
178f0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
17900 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
17910 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
17920 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
17930 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
17940 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
17950 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
17960 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
17970 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
17980 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
17990 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
179a0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
179b0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
179c0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
179d0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
179e0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
179f0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
17a00 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31 32 37 36  me Limits {F1276
17a10 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
17a20 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
17a30 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
17a40 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
17a50 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
17a60 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
17a70 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
17a80 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
17a90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
17aa0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
17ab0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
17ac0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
17ad0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
17ae0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
17af0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
17b00 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
17b10 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
17b20 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
17b30 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
17b40 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
17b50 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
17b60 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
17b70 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
17b80 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
17b90 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
17ba0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
17bb0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
17bc0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
17bd0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
17be0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
17bf0 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74  hanged..** For t
17c00 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
17c10 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
17c20 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
17c30 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62   hard upper.** b
17c40 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f  ound set by a co
17c50 6d 70 69 6c 65 2d 74 69 6d 65 20 43 2d 70 72 65  mpile-time C-pre
17c60 70 72 6f 63 65 73 73 20 6d 61 63 72 6f 20 6e 61  process macro na
17c70 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58  med SQLITE_MAX_X
17c80 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  YZ..** (The "_LI
17c90 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
17ca0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
17cb0 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74  "_MAX_".).** Att
17cc0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
17cd0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
17ce0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
17cf0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
17d00 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
17d10 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
17d20 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75   limit..**.** Ru
17d30 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n time limits ar
17d40 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
17d50 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
17d60 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
17d70 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
17d80 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
17d90 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
17da0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
17db0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
17dc0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
17dd0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
17de0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
17df0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
17e00 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61  * webbrowser tha
17e10 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
17e20 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
17e30 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
17e40 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
17e50 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
17e60 20 62 79 20 6a 61 76 61 73 63 72 69 70 74 20 61   by javascript a
17e70 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
17e80 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
17e90 65 20 69 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e internet.  The
17ea0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
17eb0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
17ec0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
17ed0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
17ee0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
17ef0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
17f00 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
17f10 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
17f20 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
17f30 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
17f40 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
17f50 65 0a 2a 2a 20 61 74 74 61 63 68 2e 20 20 44 65  e.** attach.  De
17f60 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
17f70 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
17f80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
17f90 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
17fa0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
17fb0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
17fc0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
17fd0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
17fe0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
17ff0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
18000 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
18010 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
18020 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
18030 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
18040 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  ]..**.** This in
18050 74 65 72 66 61 63 65 20 69 73 20 63 75 72 72 65  terface is curre
18060 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20  ntly considered 
18070 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
18080 20 69 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74   is subject.** t
18090 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f  o change or remo
180a0 76 61 6c 20 77 69 74 68 6f 75 74 20 70 72 69 6f  val without prio
180b0 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20  r notice..**.** 
180c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
180d0 2a 20 7b 46 31 32 37 36 32 7d 20 41 20 73 75 63  * {F12762} A suc
180e0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
180f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
18100 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
18110 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  s.**          po
18120 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74  sitive changes t
18130 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  he.**          l
18140 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
18150 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
18160 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  in [database con
18170 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
18180 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6c 65         to the le
18190 73 73 6f 72 20 6f 66 20 56 20 61 6e 64 20 74 68  ssor of V and th
181a0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
181b0 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 0a 2a  nd on the size.*
181c0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 43 20  *          of C 
181d0 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63  that is set at c
181e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a  ompile-time..**.
181f0 2a 2a 20 7b 46 31 32 37 36 36 7d 20 41 20 73 75  ** {F12766} A su
18200 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
18210 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
18220 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
18230 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
18240 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 74          leaves t
18250 68 65 20 73 74 61 74 65 20 6f 66 20 5b 64 61 74  he state of [dat
18260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18270 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ] D unchanged..*
18280 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d 20 41 20  *.** {F12769} A 
18290 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
182a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
182b0 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e  t(D,C,V)] return
182c0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
182d0 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c    value of the l
182e0 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
182f0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
18300 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  in.**          i
18310 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
18320 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20  ection] D as it 
18330 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65  was prior to the
18340 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   call..*/.int sq
18350 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
18360 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
18370 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
18380 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
18390 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
183a0 6f 72 69 65 73 20 7b 46 31 32 37 39 30 7d 0a 2a  ories {F12790}.*
183b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
183c0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69  it category} {li
183d0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
183e0 2a 2a 20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  ** .** These con
183f0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
18400 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66  rious aspects of
18410 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
18420 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74  nection].** that
18430 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20   can be limited 
18440 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73  in size by calls
18450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
18460 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65  it()]..** The me
18470 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
18480 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65  rious limits are
18490 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
184a0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
184b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
184c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
184d0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
184e0 6f 66 20 61 6e 79 0a 2a 2a 20 73 74 72 69 6e 67  of any.** string
184f0 20 6f 72 20 62 6c 6f 62 20 6f 72 20 74 61 62 6c   or blob or tabl
18500 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a  e row.<dd>.**.**
18510 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18520 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
18530 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
18540 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
18550 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
18560 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18570 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
18580 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
18590 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
185a0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
185b0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
185c0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
185d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
185e0 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d   SELECT or the m
185f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18600 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
18610 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
18620 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
18630 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
18640 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18650 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
18660 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
18670 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
18680 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
18690 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
186a0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ession.</dd>.**.
186b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
186c0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
186d0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
186e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
186f0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
18700 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
18710 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
18720 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18730 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
18740 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18750 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18760 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
18770 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
18780 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
18790 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
187a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
187b0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
187c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
187d0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
187e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
187f0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
18800 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
18810 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
18820 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18830 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
18840 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18850 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74  mum number of at
18860 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
18870 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18880 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
18890 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
188a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
188b0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
188c0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
188d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
188e0 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20  LIKE or.** GLOB 
188f0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a  operators.</dd>.
18900 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18910 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
18920 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
18930 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18940 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
18950 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
18960 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
18970 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
18980 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
18990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
189a0 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
189b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
189c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
189d0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
189e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
189f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
18a00 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
18a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18a20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a30 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
18a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18a50 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
18a60 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
18a70 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
18a80 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
18a90 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
18aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18ab0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
18ac0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
18ad0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
18ae0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
18af0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
18b00 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
18b10 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
18b20 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
18b30 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
18b40 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
18b50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
18b60 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
18b70 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43        9../*.** C
18b80 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
18b90 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
18ba0 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a  ent {F13010}.**.
18bb0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
18bc0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
18bd0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
18be0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
18bf0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
18c00 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
18c10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a  hese routines. .
18c20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
18c30 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73  argument "db" is
18c40 20 61 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   an [database co
18c50 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62  nnection] .** ob
18c60 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
18c70 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
18c80 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
18c90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
18ca0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
18cb0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20  _open16()]. .** 
18cc0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
18cd0 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68  ent "zSql" is th
18ce0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
18cf0 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
18d00 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
18d10 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
18d20 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
18d30 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
18d40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18d50 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
18d60 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73  uses UTF-8 and s
18d70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
18d80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
18d90 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
18da0 20 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e   use UTF-16. {EN
18db0 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  D}.**.** If the 
18dc0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
18dd0 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a  s less.** than z
18de0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
18df0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
18e00 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
18e10 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42  inator..** If nB
18e20 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
18e30 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
18e40 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
18e50 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20  er of .** bytes 
18e60 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
18e70 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e   When nByte is n
18e80 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
18e90 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
18ea0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
18eb0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
18ec0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
18ed0 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 74 68 65  acter or .** the
18ee0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
18ef0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
18f00 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
18f10 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
18f20 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
18f30 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
18f40 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
18f50 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
18f60 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
18f70 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 68  dvantage to be h
18f80 61 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ad by passing an
18f90 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
18fa0 20 74 68 61 74 20 0a 2a 2a 20 69 73 20 65 71 75   that .** is equ
18fb0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
18fc0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
18fd0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
18fe0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 20 0a  >including</i> .
18ff0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
19000 6e 61 74 6f 72 20 62 79 74 65 73 2e 7b 45 4e 44  nator bytes.{END
19010 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  }.**.** *pzTail 
19020 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
19030 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
19040 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
19050 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
19060 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
19070 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
19080 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70  utines only comp
19090 69 6c 65 73 20 74 68 65 20 66 69 72 73 74 0a 2a  iles the first.*
190a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  * statement in z
190b0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
190c0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
190d0 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73   to what remains
190e0 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  .** uncompiled..
190f0 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73  **.** *ppStmt is
19100 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
19110 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
19120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
19130 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
19140 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
19150 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19160 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69  .  Or if there i
19170 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
19180 74 6d 74 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f  tmt is.** set to
19190 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
191a0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
191b0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
191c0 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e  e input.** is an
191d0 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  d empty string o
191e0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
191f0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
19200 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31   to NULL..** {U1
19210 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
19220 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
19230 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
19240 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63  eleting the.** c
19250 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
19260 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  ement.** using [
19270 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
19280 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
19290 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
192a0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
192b0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
192c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
192d0 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20  therwise an .** 
192e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
192f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
19300 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
19310 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
19320 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
19330 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
19340 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
19350 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
19360 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
19370 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
19380 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
19390 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
193a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
193b0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
193c0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49  iscouraged..** I
193d0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
193e0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
193f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
19400 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
19410 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
19420 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
19430 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
19440 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61   the .** origina
19450 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b 45 4e 44  l SQL text. {END
19460 7d 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  } This causes th
19470 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
19480 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
19490 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66  ** behave a diff
194a0 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77  erently in two w
194b0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
194c0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68  ** <li>.** If th
194d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
194e0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
194f0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
19500 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
19510 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
19520 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
19530 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19540 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
19550 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
19560 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
19570 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
19580 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20   again.  If the 
19590 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67  schema has chang
195a0 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74  ed in.** a way t
195b0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74  hat makes the st
195c0 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65  atement no longe
195d0 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65  r valid, [sqlite
195e0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73  3_step()] will s
195f0 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  till.** return [
19600 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20  SQLITE_SCHEMA]. 
19610 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20   But unlike the 
19620 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c  legacy behavior,
19630 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48   .** [SQLITE_SCH
19640 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61 20 66 61  EMA] is now a fa
19650 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
19660 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
19670 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
19680 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
19690 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
196a0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
196b0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
196c0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
196d0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
196e0 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
196f0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
19700 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
19710 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a  ] return. {END}.
19720 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
19730 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65  li>.** When an e
19740 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a  rror occurs, .**
19750 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19760 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
19770 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
19780 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  d .** [error cod
19790 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
197a0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 0a   error codes]. .
197b0 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  ** The legacy be
197c0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 20  havior was that 
197d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
197e0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
197f0 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20  rn a generic.** 
19800 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
19810 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20 79  esult code and y
19820 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
19830 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
19840 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
19850 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
19860 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
19870 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
19880 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
19890 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
198a0 32 22 20 70 72 65 70 61 72 65 20 69 6e 74 65 72  2" prepare inter
198b0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
198c0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
198d0 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a   the error is.**
198e0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
198f0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
19900 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
19910 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
19920 20 7b 46 31 33 30 31 31 7d 20 54 68 65 20 5b 73   {F13011} The [s
19930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
19940 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64  b,zSql,...)] and
19950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
19960 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19970 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
19980 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
19990 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
199a0 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
199b0 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
199c0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   as UTF-8..**.**
199d0 20 7b 46 31 33 30 31 32 7d 20 54 68 65 20 5b 73   {F13012} The [s
199e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
199f0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
19a00 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
19a10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
19a20 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  6_v2(db,zSql,...
19a30 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
19a40 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
19a50 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
19a60 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
19a70 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69  eter as UTF-16 i
19a80 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
19a90 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
19aa0 46 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e  F13013} If the n
19ab0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
19ac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19ad0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
19ae0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
19af0 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
19b00 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68  iants is less th
19b10 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 53 51  an zero, then SQ
19b20 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20  L text is.**    
19b30 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20        read from 
19b40 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
19b50 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
19b60 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
19b70 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66 20  .** {F13014} If 
19b80 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
19b90 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  nt to [sqlite3_p
19ba0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
19bb0 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a  l,nByte,...)].**
19bc0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74            and it
19bd0 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f  s variants is no
19be0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
19bf0 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20   at most nBytes 
19c00 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
19c10 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65    SQL text is re
19c20 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a  ad from zSql..**
19c30 0a 2a 2a 20 7b 46 31 33 30 31 35 7d 20 49 6e 20  .** {F13015} In 
19c40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19c50 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c  _v2(db,zSql,N,P,
19c60 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73  pzTail)] and its
19c70 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20   variants.**    
19c80 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71        if the zSq
19c90 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  l input text con
19ca0 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20  tains more than 
19cb0 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  one SQL statemen
19cc0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  t.**          an
19cd0 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  d pzTail is not 
19ce0 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61  NULL, then *pzTa
19cf0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
19d00 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  int to the.**   
19d10 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74         first byt
19d20 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
19d30 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
19d40 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
19d50 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  l..**          <
19d60 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a  todo>What does *
19d70 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20  pzTail point to 
19d80 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20  if there is one 
19d90 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f  statement?</todo
19da0 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d  >.**.** {F13016}
19db0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
19dc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ll to [sqlite3_p
19dd0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
19de0 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d  l,N,ppStmt,...)]
19df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
19e00 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
19e10 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20  nts writes into 
19e20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65  *ppStmt a pointe
19e30 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20  r to a new.**   
19e40 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
19e50 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61   statement] or a
19e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c   pointer to NULL
19e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
19e80 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  zSql contains no
19e90 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
19ea0 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63   whitespace or c
19eb0 6f 6d 6d 65 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20  omments. .**.** 
19ec0 7b 46 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71  {F13019} The [sq
19ed0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19ee0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
19ef0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72  d its variants r
19f00 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
19f10 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72    [SQLITE_OK] or
19f20 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
19f30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
19f40 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
19f50 20 7b 46 31 33 30 32 31 7d 20 42 65 66 6f 72 65   {F13021} Before
19f60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19f70 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  e(db,zSql,nByte,
19f80 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20  ppStmt,pzTail)] 
19f90 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  or its.**       
19fa0 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75     variants retu
19fb0 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e  rns an error (an
19fc0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
19fd0 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a  an [SQLITE_OK]).
19fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 66  **          it f
19ff0 69 72 73 74 20 73 65 74 73 20 2a 70 70 53 74 6d  irst sets *ppStm
1a000 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  t to NULL..*/.in
1a010 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1a020 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1a030 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1a040 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1a050 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1a060 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1a070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1a080 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1a090 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1a0a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1a0b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1a0c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1a0d0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1a0e0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1a0f0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1a100 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1a110 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1a120 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1a130 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1a140 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1a150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1a160 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1a170 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1a180 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1a190 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1a1a0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1a1b0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1a1c0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1a1d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1a1e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1a1f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1a200 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1a210 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1a220 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1a230 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1a240 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1a250 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1a260 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1a270 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1a280 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1a290 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1a2a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1a2b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1a2c0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1a2d0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1a2e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1a2f0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1a300 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1a310 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1a320 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1a330 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1a340 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1a350 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1a360 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1a370 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1a380 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1a390 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1a3a0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1a3b0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1a3c0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1a3d0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1a3e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1a3f0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1a400 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1a410 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1a420 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1a430 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1a440 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1a450 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1a460 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1a470 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1a480 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1a490 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1a4a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1a4b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1a4c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1a4d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1a4e0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1a4f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1a500 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1a510 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1a520 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1a530 49 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  IREF: Retrieving
1a540 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b   Statement SQL {
1a550 46 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13100}.**.** Th
1a560 69 73 20 69 6e 74 65 72 65 66 61 63 65 20 63 61  is intereface ca
1a570 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
1a580 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
1a590 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
1a5a0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
1a5b0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
1a5c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1a5d0 65 6e 74 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ent]..**.** INVA
1a5e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1a5f0 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
1a600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a610 74 5d 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a  t] passed as .**
1a620 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 6e            the an
1a630 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1a640 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73  lite3_sql()] was
1a650 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20   compiled.**    
1a660 20 20 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75        compiled u
1a670 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1a680 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a690 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1a6a0 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1a6b0 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20  re16_v2()],.**  
1a6c0 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
1a6d0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e  lite3_sql()] fun
1a6e0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1a6f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
1a700 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1a710 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
1a720 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46  containing a UTF
1a730 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20  -8 rendering.** 
1a740 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1a750 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61  original SQL sta
1a760 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tement..**.** {F
1a770 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70  13102} If the [p
1a780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a790 74 5d 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a  t] passed as .**
1a7a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 6e            the an
1a7b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1a7c0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73  lite3_sql()] was
1a7d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20   compiled.**    
1a7e0 20 20 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75        compiled u
1a7f0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1a800 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1a810 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1a820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1a830 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1a840 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
1a850 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  sql()] function 
1a860 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1a870 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
1a880 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
1a890 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  g returned by [s
1a8a0 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69  qlite3_sql(S)] i
1a8b0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
1a8c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1a8d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a8e0 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20  t] S is deleted 
1a8f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1a900 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a  inalize(S)]..*/.
1a910 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1a920 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
1a930 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1a940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1a950 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
1a960 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 20  d Value Object  
1a970 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F15000}.** KEYW
1a980 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
1a990 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
1a9a0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
1a9b0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
1a9c0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
1a9d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1a9e0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
1a9f0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
1aa00 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
1aa10 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
1aa20 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c  se table..** SQL
1aa30 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
1aa40 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20   typing for the 
1aa50 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
1aa60 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74  .  .** Values st
1aa70 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
1aa80 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61  value objects ca
1aa90 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67  n be.** be integ
1aaa0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
1aab0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
1aac0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
1aad0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
1aae0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1aaf0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
1ab00 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
1ab10 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
1ab20 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
1ab30 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
1ab40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ab50 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
1ab60 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
1ab70 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
1ab80 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
1ab90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1aba0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
1abb0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
1abc0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
1abd0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
1abe0 73 20 73 70 65 63 69 66 69 65 73 20 0a 2a 2a 20  s specifies .** 
1abf0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1ac00 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1ac10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1ac20 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1ac30 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1ac40 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1ac50 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1ac60 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1ac70 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1ac80 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1ac90 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1aca0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1acb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1acc0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1acd0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1ace0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1acf0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ad00 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1ad10 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1ad20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1ad30 2a 2a 20 28 77 69 74 68 20 53 51 4c 49 54 45 5f  ** (with SQLITE_
1ad40 54 48 52 45 41 44 53 41 46 45 3d 30 20 61 6e 64  THREADSAFE=0 and
1ad50 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
1ad60 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
1ad70 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 74 68 65  urning 0).** the
1ad80 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
1ad90 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1ada0 6e 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 61  n.** protected a
1adb0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  nd unprotected s
1adc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1add0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
1ade0 6e 20 62 65 0a 2a 2a 20 75 73 65 64 20 69 6e 74  n be.** used int
1adf0 65 72 63 68 61 6e 67 61 62 6c 65 2e 20 20 48 6f  erchangable.  Ho
1ae00 77 65 76 65 72 2c 20 66 6f 72 20 6d 61 78 69 6d  wever, for maxim
1ae10 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1ae20 69 74 79 20 69 74 0a 2a 2a 20 69 73 20 72 65 63  ity it.** is rec
1ae30 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
1ae40 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61 6b 65 20  plications make 
1ae50 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1ae60 62 65 74 77 65 65 6e 0a 2a 2a 20 62 65 74 77 65  between.** betwe
1ae70 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1ae80 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
1ae90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1aea0 74 73 20 65 76 65 6e 20 69 66 0a 2a 2a 20 74 68  ts even if.** th
1aeb0 65 79 20 61 72 65 20 73 69 6e 67 6c 65 20 74 68  ey are single th
1aec0 72 65 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  readed..**.** Th
1aed0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1aee0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
1aef0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
1af00 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
1af10 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1af20 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   of application-
1af30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1af40 74 69 6f 6e 73 20 61 72 65 20 70 72 6f 74 65 63  tions are protec
1af50 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
1af60 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1af70 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1af80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1af90 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1afa0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1afb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1afc0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1afd0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1afe0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1aff0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1b000 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1b010 64 5f 76 61 6c 75 65 28 29 5d 2e 20 20 41 6c 6c  d_value()].  All
1b020 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
1b030 61 63 65 73 20 74 68 61 74 20 75 73 65 20 73 71  aces that use sq
1b040 6c 69 74 65 33 5f 76 61 6c 75 65 20 72 65 71 75  lite3_value requ
1b050 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
1b060 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1b070 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
1b080 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
1b090 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
1b0a0 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20   CAPI3REF:  SQL 
1b0b0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
1b0c0 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d   Object {F16001}
1b0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
1b0e0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
1b0f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
1b100 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
1b110 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
1b120 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
1b130 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
1b140 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1b150 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c  .** object is al
1b160 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1b170 65 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  eter to applicat
1b180 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1b190 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79  functions..*/.ty
1b1a0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1b1b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1b1c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1b1d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1b1e0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1b1f0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1b200 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a  ments {F13500}.*
1b210 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20  *.** In the SQL 
1b220 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f  strings input to
1b230 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b240 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a  e_v2()] and its.
1b250 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74  ** variants, lit
1b260 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1b270 6c 61 63 65 20 62 79 20 61 20 70 61 72 61 6d 65  lace by a parame
1b280 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66  ter in one.** of
1b290 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a   these forms:.**
1b2a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1b2b0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
1b2c0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
1b2d0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
1b2e0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
1b2f0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
1b300 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d  e parameter form
1b310 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e  s shown above NN
1b320 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  N is an integer 
1b330 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20  literal,.** VVV 
1b340 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
1b350 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a  rameter name..**
1b360 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
1b370 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
1b380 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
1b390 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1b3a0 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70  es".** or "SQL p
1b3b0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
1b3c0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
1b3d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1b3e0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
1b3f0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
1b400 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1b410 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1b420 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1b430 74 69 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20  tines always.** 
1b440 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1b450 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1b460 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1b470 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1b480 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b490 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1b4a0 73 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  s. The second.**
1b4b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1b4c0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61   index of the pa
1b4d0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
1b4e0 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20  t. The.** first 
1b4f0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1b500 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
1b510 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1b520 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
1b530 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
1b540 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
1b550 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
1b560 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
1b570 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
1b580 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
1b590 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65  urrence. .** The
1b5a0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
1b5b0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
1b5c0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
1b5d0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
1b5e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b5f0 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66  r_name()] API if
1b600 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69   desired.  The i
1b610 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
1b620 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
1b630 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
1b640 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61  N..** The NNN va
1b650 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
1b660 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f  een 1 and the co
1b670 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61  mpile-time.** pa
1b680 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d  rameter SQLITE_M
1b690 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1b6a0 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  ER (default valu
1b6b0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54  e: 999)..**.** T
1b6c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1b6d0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
1b6e0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
1b6f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
1b700 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69  n those.** routi
1b710 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1b720 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1b730 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1b740 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1b750 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61  s.** in the para
1b760 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1b770 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1b780 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b790 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20  <u>bytes</u>.** 
1b7a0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1b7b0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1b7c0 63 68 61 72 61 63 74 65 72 73 2e 20 0a 2a 2a 20  characters. .** 
1b7d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1b7e0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
1b7f0 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
1b800 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
1b810 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
1b820 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
1b830 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1b840 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  tor..**.** The f
1b850 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
1b860 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1b870 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
1b880 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
1b890 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
1b8a0 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
1b8b0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
1b8c0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
1b8d0 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
1b8e0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
1b8f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1b900 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68  it. If the fifth
1b910 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
1b920 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
1b930 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
1b940 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
1b950 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
1b960 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1b970 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
1b980 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
1b990 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1b9a0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49  o be freed..** I
1b9b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1b9c0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
1b9d0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
1b9e0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
1b9f0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
1ba00 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
1ba10 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
1ba20 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
1ba30 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
1ba40 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1ba50 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1ba60 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1ba70 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
1ba80 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
1ba90 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
1baa0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
1bab0 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65  ith zeros.  A ze
1bac0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
1bad0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
1bae0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
1baf0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
1bb00 20 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20   it size) while 
1bb10 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1bb20 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1bb30 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1bb40 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1bb50 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  ce-holders for B
1bb60 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
1bb70 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
1bb80 72 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a  ritten using .**
1bb90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
1bba0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20  pen | increment 
1bbb0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1bbc0 65 73 2e 20 41 20 6e 65 67 61 74 69 76 65 0a 2a  es. A negative.*
1bbd0 2a 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  * value for the 
1bbe0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
1bbf0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
1bc00 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68  h BLOB..**.** Th
1bc10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1bc20 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  () routines must
1bc30 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72   be called after
1bc40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1bc50 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20  pare_v2()] (and 
1bc60 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72  its variants) or
1bc70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1bc80 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65  )] and.** before
1bc90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1bca0 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61  ]..** Bindings a
1bcb0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
1bcc0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
1bcd0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
1bce0 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61  .** Unbound para
1bcf0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
1bd00 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
1bd10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1bd20 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
1bd30 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
1bd40 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63  ss or an error c
1bd50 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69  ode if.** anythi
1bd60 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20  ng goes wrong.  
1bd70 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
1bd80 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
1bd90 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
1bda0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
1bdb0 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e  ange.  [SQLITE_N
1bdc0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
1bdd0 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c  d if malloc fail
1bde0 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1bdf0 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1be00 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1be10 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1be20 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1be30 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1be40 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1be50 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1be60 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1be70 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1be80 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1be90 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1bea0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1beb0 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1bec0 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1bed0 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1bee0 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1bef0 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1bf00 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1bf10 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1bf20 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1bf30 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1bf40 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1bf50 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1bf60 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1bf70 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1bf80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1bf90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1bfa0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1bfb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1bfc0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1bfd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1bfe0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1bff0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1c000 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1c010 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13506} The [sqli
1c020 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51  te3_prepare | SQ
1c030 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1c040 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73  iler] recognizes
1c050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b  .**          tok
1c060 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  ens of the forms
1c070 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24   "?", "?NNN", "$
1c080 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e  VVV", ":VVV", an
1c090 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20 20 20  d "@VVV".**     
1c0a0 20 20 20 20 20 61 73 20 53 51 4c 20 70 61 72 61       as SQL para
1c0b0 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20 4e 4e  meters, where NN
1c0c0 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  N is any sequenc
1c0d0 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
1c0e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69 67  .**          dig
1c0f0 69 74 73 20 61 6e 64 20 77 68 65 72 65 20 56 56  its and where VV
1c100 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  V is any sequenc
1c110 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
1c120 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c   .**          al
1c130 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61 72 61  phanumeric chara
1c140 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70  cters or "::" op
1c150 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
1c160 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1c170 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69   a string contai
1c180 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73 20 61  ning no spaces a
1c190 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  nd contained wit
1c1a0 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e  hin parentheses.
1c1b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20  .**.** {F13509} 
1c1c0 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75  The initial valu
1c1d0 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  e of an SQL para
1c1e0 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  meter is NULL..*
1c1f0 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54 68  *.** {F13512} Th
1c200 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
1c210 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
1c220 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68  is one larger th
1c230 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  an the.**       
1c240 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78     largest index
1c250 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
1c260 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f  r to the left, o
1c270 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  r 1 if.**       
1c280 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68     the "?" is th
1c290 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1c2a0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1c2b0 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64  {F13515} The ind
1c2c0 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20  ex of an "?NNN" 
1c2d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1c2e0 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e   the integer NNN
1c2f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d  ..**.** {F13518}
1c300 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
1c310 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c   ":VVV", "$VVV",
1c320 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70   or "@VVV" SQL p
1c330 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
1c340 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
1c350 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   as the index of
1c360 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 61   leftmost occura
1c370 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65  nces of the same
1c380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
1c390 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d  ameter, or one m
1c3a0 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72  ore than the lar
1c3b0 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20  gest index over 
1c3c0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
1c3d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1c3e0 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69  e left if this i
1c3f0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1c400 72 72 61 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20  rrance.**       
1c410 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d     of this param
1c420 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68  eter, or 1 if th
1c430 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  is is the leftmo
1c440 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
1c450 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65  .** {F13521} The
1c460 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c470 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  e | SQL statemen
1c480 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c  t compiler] fail
1c490 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
1c4a0 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e    an [SQLITE_RAN
1c4b0 47 45 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65  GE] error if the
1c4c0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
1c4d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
1c4e0 20 20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74         is less t
1c4f0 68 61 6e 20 31 20 6f 72 20 67 72 65 61 74 65 72  han 1 or greater
1c500 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41 58   than SQLITE_MAX
1c510 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c520 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d  ..**.** {F13524}
1c530 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
1c540 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c550 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c  qlite3_bind(S,N,
1c560 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  V,...)].**      
1c570 20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68      associate th
1c580 65 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61  e value V with a
1c590 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
1c5a0 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20  s having an.**  
1c5b0 20 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66          index of
1c5c0 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61   N in the [prepa
1c5d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1c5e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d  ..**.** {F13527}
1c5f0 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
1c600 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c610 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c  qlite3_bind(S,N,
1c620 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1c630 20 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72    override prior
1c640 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20   calls with the 
1c650 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53  same values of S
1c660 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46   and N..**.** {F
1c670 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20  13530} Bindings 
1c680 65 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b  established by [
1c690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c6a0 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
1c6b0 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  (S,...)].**     
1c6c0 20 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72       persist acr
1c6d0 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  oss calls to [sq
1c6e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
1c6f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20  .**.** {F13533} 
1c700 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1c710 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
1c720 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
1c730 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c740 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
1c750 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
1c760 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c770 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
1c780 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62  V,L,D)] SQLite b
1c790 69 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c  inds the first L
1c7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74  .**          byt
1c7b0 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 6f  es of the blob o
1c7c0 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  r string pointed
1c7d0 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c   to by V, when L
1c7e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1c7f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
1c800 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20  .** {F13536} In 
1c810 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1c820 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1c830 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20  V,L,D)] or.**   
1c840 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c850 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
1c860 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62  V,L,D)] SQLite b
1c870 69 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a  inds characters.
1c880 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
1c890 20 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66   V through the f
1c8a0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
1c8b0 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65  ter when L is ne
1c8c0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
1c8d0 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20  13539} In calls 
1c8e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1c8f0 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
1c900 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
1c910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c920 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
1c930 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1c940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c950 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
1c960 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
1c970 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
1c980 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
1c990 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74  E_STATIC], SQLit
1c9a0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1c9b0 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20  he value V.**   
1c9c0 20 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69         is held i
1c9d0 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67  n static unmanag
1c9e0 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69  ed space that wi
1c9f0 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a  ll not change.**
1ca00 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67            during
1ca10 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
1ca20 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a   the binding..**
1ca30 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20  .** {F13542} In 
1ca40 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1ca50 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
1ca60 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
1ca70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1ca80 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
1ca90 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
1caa0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1cab0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1cac0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
1cad0 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
1cae0 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
1caf0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
1cb00 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20  T], the routine 
1cb10 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20 20  makes a .**     
1cb20 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f 70       private cop
1cb30 79 20 6f 66 20 56 20 76 61 6c 75 65 20 62 65 66  y of V value bef
1cb40 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
1cb50 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20 49  **.** {F13545} I
1cb60 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1cb70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
1cb80 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
1cb90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1cba0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
1cbb0 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
1cbc0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
1cbd0 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
1cbe0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
1cbf0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
1cc00 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63            a func
1cc10 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76  tion, SQLite inv
1cc20 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69  okes that functi
1cc30 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68  on to destroy th
1cc40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20  e.**          V 
1cc50 76 61 6c 75 65 20 61 66 74 65 72 20 69 74 20 68  value after it h
1cc60 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
1cc70 67 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  g the V value..*
1cc80 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49 6e  *.** {F13548} In
1cc90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1cca0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1ccb0 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76  (S,N,V,L)] the v
1ccc0 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20  alue bound.**   
1ccd0 20 20 20 20 20 20 20 69 73 20 61 20 62 6c 6f 62         is a blob
1cce0 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20   of L bytes, or 
1ccf0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c  a zero-length bl
1cd00 6f 62 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74  ob if L is negat
1cd10 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ive..**.** {F135
1cd20 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  51} In calls to 
1cd30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1cd40 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20  lue(S,N,V)] the 
1cd50 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a  V argument may.*
1cd60 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69  *          be ei
1cd70 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65  ther a [protecte
1cd80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
1cd90 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a   object or an.**
1cda0 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f            [unpro
1cdb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1cdc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  alue] object..*/
1cdd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1cde0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1cdf0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1ce00 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1ce10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1ce20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1ce30 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1ce40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1ce50 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1ce60 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1ce70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1ce80 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1ce90 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1cea0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1ceb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1cec0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ced0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1cee0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1cef0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1cf00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1cf10 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1cf20 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1cf30 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1cf40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1cf50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1cf60 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1cf70 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1cf80 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1cf90 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1cfa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1cfb0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1cfc0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1cfd0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1cfe0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1cff0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1d000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d010 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1d020 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36 30  arameters {F1360
1d030 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
1d040 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
1d050 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
1d060 6d 62 65 72 20 6f 66 20 53 51 4c 20 70 61 72 61  mber of SQL para
1d070 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20 70  meters.** in a p
1d080 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d090 74 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  t.  SQL paramete
1d0a0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
1d0b0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
1d0c0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
1d0d0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
1d0e0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
1d0f0 73 0a 2a 2a 20 70 6c 61 63 65 2d 68 6f 6c 64 65  s.** place-holde
1d100 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1d110 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1d120 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1d130 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1d140 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1d150 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
1d160 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
1d170 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1d180 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
1d190 72 67 65 73 74 20 70 61 72 61 6d 65 74 65 72 2e  rgest parameter.
1d1a0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  .** For all form
1d1b0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
1d1c0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
1d1d0 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ond to the numbe
1d1e0 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70  r of.** unique p
1d1f0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
1d200 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1d210 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 20   ?NNN are used, 
1d220 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20  there may.** be 
1d230 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
1d240 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1d250 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1d260 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1d270 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1d280 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d290 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1d2a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d2b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1d2c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1d2d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
1d2e0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1d2f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d300 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
1d310 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
1d320 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67          the larg
1d330 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c  est index of all
1d340 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1d350 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
1d360 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1d370 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
1d380 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  if S.**         
1d390 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1d3a0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
1d3b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1d3c0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1d3d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1d3e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d3f0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1d400 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31 33 36   Parameter {F136
1d410 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  20}.**.** This r
1d420 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1d430 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1d440 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
1d450 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1d460 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  r in a [prepared
1d470 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1d480 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1d490 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1d4a0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1d4b0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1d4c0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1d4d0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1d4e0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1d4f0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1d500 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1d510 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1d520 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1d530 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1d540 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1d550 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1d560 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1d570 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
1d580 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
1d590 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
1d5a0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
1d5b0 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a  ave no name..**.
1d5c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73  ** The first hos
1d5d0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
1d5e0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
1d5f0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ot 0..**.** If t
1d600 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75  he value n is ou
1d610 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
1d620 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65   the n-th parame
1d630 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
1d640 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
1d650 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1d660 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1d670 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
1d680 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1d690 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
1d6a0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
1d6b0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
1d6c0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
1d6d0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
1d6e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
1d6f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d700 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
1d710 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1d720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1d730 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1d740 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1d750 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1d760 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
1d770 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d780 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1d790 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1d7a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d  :.**.** {F13621}
1d7b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
1d7c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1d7d0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
1d7e0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
1d7f0 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65        a UTF-8 re
1d800 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
1d810 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
1d820 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20  arameter in.**  
1d830 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1d840 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
1d850 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f  aving index N, o
1d860 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55  r.**          NU
1d870 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
1d880 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  o SQL parameter 
1d890 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20  with index N or 
1d8a0 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
1d8b0 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74     parameter wit
1d8c0 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20  h index N is an 
1d8d0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
1d8e0 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73  ter "?"..*/.cons
1d8f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1d900 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1d910 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1d920 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
1d930 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
1d940 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
1d950 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
1d960 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13640}.**.** 
1d970 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1d980 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1d990 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1d9a0 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64  ame.  The.** ind
1d9b0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
1d9c0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
1d9d0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
1d9e0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
1d9f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1da00 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1da10 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a  ind()].  A zero.
1da20 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1da30 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
1da40 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
1da50 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72  .  The parameter
1da60 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
1da70 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
1da80 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
1da90 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
1daa0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
1dab0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
1dac0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1dad0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1dae0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1daf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1db00 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1db10 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1db20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1db30 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
1db40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1db50 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1db60 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1db70 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34  TS:.**.** {F1364
1db80 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1db90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1dba0 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ndex(S,N)] inter
1dbb0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
1dbc0 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64           the ind
1dbd0 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
1dbe0 74 65 72 20 69 6e 20 5b 70 72 65 70 61 72 65 64  ter in [prepared
1dbf0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
1dc00 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20          S whose 
1dc10 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65  name matches the
1dc20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c   UTF-8 string N,
1dc30 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69   or 0 if there i
1dc40 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  s.**          no
1dc50 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73   match..*/.int s
1dc60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1dc70 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
1dc80 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
1dc90 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
1dca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dcb0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
1dcc0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
1dcd0 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 36   Statement {F136
1dce0 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  60}.**.** Contra
1dcf0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
1dd00 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
1dd10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
1dd20 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74  oes not.** reset
1dd30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
1dd40 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
1dd50 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72  gs] on a .** [pr
1dd60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1dd70 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75  ].  Use this rou
1dd80 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74  tine to.** reset
1dd90 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
1dda0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
1ddb0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1ddc0 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54  **.** {F13661} T
1ddd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
1dde0 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
1ddf0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
1de00 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
1de10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 62 69  SQL parameter bi
1de20 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72 65 70 61  ndings in [prepa
1de30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1de40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63  .**          bac
1de50 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  k to NULL..*/.in
1de60 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
1de70 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
1de80 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
1de90 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
1dea0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
1deb0 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
1dec0 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  710}.**.** Retur
1ded0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
1dee0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
1def0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
1df00 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70  ed by the .** [p
1df10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1df20 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
1df30 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66   returns 0.** if
1df40 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
1df50 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1df60 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
1df70 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78  data (for .** ex
1df80 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29  ample an UPDATE)
1df90 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1dfa0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31  TS:.**.** {F1371
1dfb0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1dfc0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
1dfd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1dfe0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1dff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
1e000 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
1e010 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64  lt set generated
1e020 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
1e030 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
1e040 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
1e050 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67   if S does not g
1e060 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20 20 20  enerate.**      
1e070 20 20 20 20 61 20 72 65 73 75 6c 74 20 73 65 74      a result set
1e080 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1e090 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
1e0a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1e0b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e0c0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
1e0d0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
1e0e0 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a  t {F13720}.**.**
1e0f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e100 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
1e110 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
1e120 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
1e130 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
1e140 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
1e150 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
1e160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1e170 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
1e180 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
1e190 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1e1a0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20  terminated UTF8 
1e1b0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
1e1c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e1d0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
1e1e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
1e1f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1e200 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
1e210 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1e220 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72  er is the.** [pr
1e230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e240 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  ] that implement
1e250 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61  s the SELECT sta
1e260 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  tement..** The s
1e270 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1e280 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75  is the column nu
1e290 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d  mber.  The left-
1e2a0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a  most column is.*
1e2b0 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  * number 0..**.*
1e2c0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1e2d0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
1e2e0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
1e2f0 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  her the .** [pre
1e300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e310 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
1e320 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e330 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69  ze()].** or unti
1e340 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
1e350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1e360 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
1e370 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1e380 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
1e390 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  column..**.** If
1e3a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e3b0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
1e3c0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
1e3d0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
1e3e0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
1e3f0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
1e400 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
1e410 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
1e420 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1e430 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1e440 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
1e450 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
1e460 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
1e470 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
1e480 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
1e490 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
1e4a0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
1e4b0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
1e4c0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
1e4d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1e4e0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
1e4f0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
1e500 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
1e510 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
1e520 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
1e530 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1e540 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d  :.**.** {F13721}
1e550 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
1e560 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
1e570 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e580 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  name(S,N)].**   
1e590 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1e5a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
1e5b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1e5c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1e5d0 28 77 68 65 72 65 20 30 20 69 73 20 74 68 65 20  (where 0 is the 
1e5e0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
1e5f0 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ) for the.**    
1e600 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
1e610 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
1e620 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a  atement] S as a.
1e630 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1e640 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1e650 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1e660 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63 63 65  {F13723} A succe
1e670 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
1e680 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1e690 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
1e6a0 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
1e6b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1e6c0 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
1e6d0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
1e6e0 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
1e6f0 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
1e700 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
1e710 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e720 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
1e730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e740 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
1e750 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1e760 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72  nated UTF-16 str
1e770 69 6e 67 20 69 6e 20 74 68 65 20 6e 61 74 69 76  ing in the nativ
1e780 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
1e790 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65  .** {F13724} The
1e7a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e7b0 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71  _name()] and [sq
1e7c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e7d0 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  e16()].**       
1e7e0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
1e7f0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
1e800 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20  ter if they are 
1e810 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20  unable to.**    
1e820 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d        allocate m
1e830 65 6d 6f 72 79 20 6d 65 6d 6f 72 79 20 74 6f 20  emory memory to 
1e840 68 6f 6c 64 20 74 68 65 72 65 20 6e 6f 72 6d 61  hold there norma
1e850 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73  l return strings
1e860 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35 7d  ..**.** {F13725}
1e870 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65   If the N parame
1e880 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e890 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
1e8a0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
1e8b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e8c0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73  _name16(S,N)] is
1e8d0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
1e8e0 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hen the.**      
1e8f0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
1e900 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1e910 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46  inter..** .** {F
1e920 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e  13726} The strin
1e930 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
1e940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1e950 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a  ame(S,N)] and.**
1e960 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1e970 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1e980 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64  (S,N)] are valid
1e990 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
1e9a0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
1e9b0 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69   to either routi
1e9c0 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ne with the same
1e9d0 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74   S and N paramet
1e9e0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
1e9f0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
1ea00 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
1ea10 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  s called..**.** 
1ea20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20  {F13727} When a 
1ea30 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1ea40 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1ea50 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a  ement contains.*
1ea60 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53  *          an AS
1ea70 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d   clause, the nam
1ea80 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e  e of that column
1ea90 20 69 73 20 74 68 65 20 69 6e 64 65 6e 74 69 66   is the indentif
1eaa0 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ier.**          
1eab0 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20  to the right of 
1eac0 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a  the AS keyword..
1ead0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1eae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1eaf0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1eb00 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
1eb10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1eb20 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
1eb30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
1eb40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1eb50 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
1eb60 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
1eb70 73 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a  sult {F13740}.**
1eb80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1eb90 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
1eba0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
1ebb0 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
1ebc0 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
1ebd0 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
1ebe0 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c   result of a SEL
1ebf0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ECT statement co
1ec00 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65  mes from..** The
1ec10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1ec20 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
1ec30 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
1ec40 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
1ec50 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20  ither a UTF8 or 
1ec60 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
1ec70 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
1ec80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
1ec90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
1eca0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
1ecb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1ecc0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
1ecd0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
1ece0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
1ecf0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
1ed00 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
1ed10 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
1ed20 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65  lid until.** the
1ed30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ed40 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
1ed50 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1ed60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1ed70 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
1ed80 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
1ed90 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
1eda0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
1edb0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
1edc0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65  .** The names re
1edd0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
1ede0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
1edf0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
1ee00 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
1ee10 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
1ee20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1ee30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1ee40 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20  following calls 
1ee50 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
1ee60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68  tatement]..** Th
1ee70 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
1ee80 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
1ee90 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63   about the Nth c
1eea0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1eeb0 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  y .** the statem
1eec0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
1eed0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
1eee0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
1eef0 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
1ef00 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1ef10 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
1ef20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
1ef30 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20  .** or subquery 
1ef40 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
1ef50 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
1ef60 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
1ef70 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
1ef80 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
1ef90 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
1efa0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
1efb0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
1efc0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
1efd0 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
1efe0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
1eff0 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65   .** name of the
1f000 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1f010 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  se, table and co
1f020 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
1f030 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
1f040 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
1f050 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
1f060 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
1f070 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
1f080 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
1f090 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
1f0a0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
1f0b0 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
1f0c0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1f0d0 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
1f0e0 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
1f0f0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
1f100 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1f110 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1f120 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
1f130 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1f140 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
1f150 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
1f160 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33  ined..**.** {U13
1f170 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
1f180 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1f190 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
1f1a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1f1b0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
1f1c0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
1f1d0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
1f1e0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
1f1f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
1f200 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
1f210 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
1f220 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1f230 7b 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {F13741} The [sq
1f240 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1f250 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
1f260 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f270 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
1f280 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
1f290 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f2a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1f2b0 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
1f2c0 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1f2d0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1f2e0 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1f2f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1f300 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1f310 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1f320 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63  if the the Nth c
1f330 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1f340 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1f350 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1f360 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1f370 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1f380 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1f390 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1f3a0 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1f3b0 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  13742} The [sqli
1f3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1f3d0 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ase_name16(S,N)]
1f3e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f3f0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
1f400 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
1f410 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1f420 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  er.**          z
1f430 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
1f440 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1f450 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
1f460 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1f470 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
1f480 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
1f490 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
1f4a0 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
1f4b0 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
1f4c0 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f  f the the Nth co
1f4d0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
1f4e0 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
1f4f0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
1f500 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
1f510 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
1f520 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
1f530 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
1f540 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
1f550 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3743} The [sqlit
1f560 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1f570 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
1f580 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1f590 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1f5a0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
1f5b0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1f5c0 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d  f the table from
1f5d0 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
1f5e0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
1f5f0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
1f600 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f610 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
1f620 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
1f630 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74 68  r NULL if the th
1f640 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
1f650 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
1f660 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
1f670 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
1f680 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1f690 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
1f6a0 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
1f6b0 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
1f6c0 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54 68   .** {F13744} Th
1f6d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1f6e0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
1f6f0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1f700 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
1f710 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
1f720 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
1f730 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
1f740 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
1f750 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
1f760 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20  able from which 
1f770 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1f780 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1f790 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1f7a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1f7b0 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1f7c0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1f7d0 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63  if the the Nth c
1f7e0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1f7f0 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1f800 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1f810 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1f820 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1f830 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1f840 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1f850 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1f860 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  13745} The [sqli
1f870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1f880 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  n_name(S,N)] int
1f890 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
1f8a0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
1f8b0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
1f8c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
1f8d0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1f8e0 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
1f8f0 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1f900 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1f910 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1f920 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1f930 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1f940 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1f950 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63  if the the Nth c
1f960 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1f970 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1f980 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1f990 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1f9a0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1f9b0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1f9c0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1f9d0 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1f9e0 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
1f9f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1fa00 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
1fa10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1fa20 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
1fa30 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
1fa40 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1fa50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1fa60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1fa70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1fa80 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
1fa90 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1faa0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1fab0 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1fac0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1fad0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1fae0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1faf0 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1fb00 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1fb10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1fb20 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1fb30 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1fb40 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1fb50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1fb60 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1fb70 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1fb80 46 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75  F13748} The retu
1fb90 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a  rn values from.*
1fba0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1fbb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1fbc0 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20  ase_name|column 
1fbd0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
1fbe0 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
1fbf0 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20 20   are valid.**   
1fc00 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6c         for the l
1fc10 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b  ifetime of the [
1fc20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fc30 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
1fc40 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63  or until the enc
1fc50 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64  oding is changed
1fc60 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61   by another meta
1fc70 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
1fc80 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1fc90 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65  for the same pre
1fca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
1fcb0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
1fcc0 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
1fcd0 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49 66  *.** {U13751} If
1fce0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1fcf0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1fd00 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
1fd10 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
1fd20 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c  n_database_name|
1fd30 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
1fd40 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
1fd50 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
1fd60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fd70 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
1fd80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
1fd90 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20      at the same 
1fda0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
1fdb0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1fdc0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
1fdd0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1fde0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1fdf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1fe00 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
1fe10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1fe20 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
1fe30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1fe40 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
1fe50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1fe60 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
1fe70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1fe80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1fe90 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1fea0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1feb0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1fec0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1fed0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1fee0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1fef0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
1ff00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1ff10 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
1ff20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1ff30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ff40 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
1ff50 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
1ff60 52 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a  Result {F13760}.
1ff70 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1ff80 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
1ff90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ffa0 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73  nt]. .** If this
1ffb0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
1ffc0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1ffd0 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
1ffe0 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72  umn of the .** r
1fff0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
20000 65 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43  et of that SELEC
20010 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  T is a table col
20020 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
20030 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
20040 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
20050 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
20060 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
20070 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
20080 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
20090 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
200a0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
200b0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
200c0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
200d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
200e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
200f0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
20100 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
20110 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20  encoded.  {END} 
20120 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
20130 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
20140 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
20150 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
20160 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
20170 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * And the follow
20180 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
20190 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
201a0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
201b0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54  FROM t1;.**.** T
201c0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
201d0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
201e0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
201f0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
20200 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75  d.** result colu
20210 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
20220 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
20230 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
20240 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d  lt column.** (i=
20250 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  =0)..**.** SQLit
20260 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
20270 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
20280 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65   So just because
20290 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
202a0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
202b0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
202c0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
202d0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
202e0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
202f0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
20300 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
20310 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
20320 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
20330 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
20340 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
20350 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a  static.  Type.**
20360 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
20370 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
20380 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
20390 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
203a0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
203b0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  hose values..**.
203c0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
203d0 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20 41  *.** {F13761}  A
203e0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
203f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
20400 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
20410 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
20420 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
20430 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
20440 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
20450 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
20460 20 20 20 74 68 65 20 64 65 63 6c 61 72 65 64 20     the declared 
20470 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
20480 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
20490 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20  t appears.**    
204a0 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74         as the Nt
204b0 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
204c0 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68  ed from 0) of th
204d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20  e result set to 
204e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
204f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20500 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
20510 46 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65  F13762}  A succe
20520 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
20530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
20540 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a  cltype16(S,N)].*
20550 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
20560 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
20570 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
20580 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
20590 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
205a0 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68     containing th
205b0 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
205c0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
205d0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
205e0 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
205f0 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
20600 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
20610 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
20620 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
20630 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
20640 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20650 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36   S..**.** {F1376
20660 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  3}  If N is less
20670 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20   than 0 or N is 
20680 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
20690 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20  equal to.**     
206a0 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72        the number
206b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b   of columns in [
206c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
206d0 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
206e0 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68     or if the Nth
206f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
20700 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
20710 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72   subquery rather
20720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
20730 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  an a table colum
20740 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  n or if a memory
20750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
20760 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
20770 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65   occurs during e
20780 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69  ncoding conversi
20790 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ons, then.**    
207a0 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20         calls to 
207b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
207c0 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f  decltype(S,N)] o
207d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
207e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
207f0 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20  ecltype16(S,N)] 
20800 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a  return NULL..*/.
20810 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
20830 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
20840 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
20850 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
20860 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
20870 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20880 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52  ;../* .** CAPI3R
20890 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e  EF:  Evaluate An
208a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
208b0 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66  F13200}.**.** Af
208c0 74 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65 64  ter an [prepared
208d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
208e0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69  been prepared wi
208f0 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20  th a call.** to 
20900 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
20910 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20930 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20  e16_v2()] or to 
20940 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65  one of.** the le
20950 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20  gacy interfaces 
20960 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20970 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20980 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
20990 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74   then this funct
209a0 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ion must be call
209b0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
209c0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
209d0 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65   the .** stateme
209e0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
209f0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
20a00 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71  avior of this sq
20a10 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
20a20 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
20a30 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
20a40 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
20a50 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
20a60 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
20a70 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
20a80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20a90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
20aa0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
20ab0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
20ac0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
20ad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20ae0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
20af0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
20b00 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
20b10 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
20b20 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
20b30 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
20b40 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
20b50 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
20b60 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
20b70 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
20b80 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c  ..**.** In the l
20b90 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
20ba0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
20bb0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
20bc0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
20bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
20be0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
20bf0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
20c00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
20c10 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
20c20 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
20c30 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
20c40 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  r [SQLITE_OK | r
20c50 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f  esult code].** o
20c60 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
20c70 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
20c80 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67  result code] mig
20c90 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
20ca0 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  s.** well..**.**
20cb0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d   [SQLITE_BUSY] m
20cc0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
20cd0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
20ce0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
20cf0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
20d00 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
20d10 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
20d20 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
20d30 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a  ent is a COMMIT.
20d40 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
20d50 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
20d60 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
20d70 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
20d80 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
20d90 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
20da0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
20db0 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75   COMMIT and occu
20dc0 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
20dd0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
20de0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
20df0 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
20e00 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
20e10 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
20e20 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  g..**.** [SQLITE
20e30 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
20e40 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
20e50 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
20e60 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
20e70 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
20e80 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
20e90 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
20ea0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
20eb0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
20ec0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
20ed0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
20ee0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
20ef0 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
20f00 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
20f10 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
20f20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
20f30 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
20f40 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
20f50 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
20f60 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  n .** [SQLITE_RO
20f70 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  W] is returned e
20f80 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
20f90 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
20fa0 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65  ady.** for proce
20fb0 73 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c  ssing by the cal
20fc0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
20fd0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
20fe0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
20ff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
21000 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73   | column access
21010 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
21020 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
21030 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
21040 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
21050 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
21060 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  .** .** [SQLITE_
21070 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
21080 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
21090 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
210a0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
210b0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
210c0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
210d0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
210e0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
210f0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
21100 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
21110 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
21120 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21130 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69  errmsg()]..** Wi
21140 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
21150 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
21160 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
21170 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a  ode (example:.**
21180 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
21190 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
211a0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
211b0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
211c0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
211d0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
211e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
211f0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
21200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21210 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76  ent].  In the "v
21220 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
21230 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
21240 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
21250 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
21260 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
21270 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
21280 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
21290 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
212a0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
212b0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
212c0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
212d0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
212e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
212f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
21300 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
21310 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21320 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
21330 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
21340 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  d .** previously
21350 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
21360 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
21370 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
21380 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
21390 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
213a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
213b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
213c0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
213d0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
213e0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
213f0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
21400 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
21410 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
21420 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
21430 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a  y interface, .**
21440 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
21450 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72  p() API always r
21460 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
21470 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20   error code,.** 
21480 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
21490 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72  following any er
214a0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
214b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
214c0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
214d0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
214e0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  all [sqlite3_res
214f0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
21500 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
21510 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
21520 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65  d one of the spe
21530 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72 20  cific.** [error 
21540 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
21550 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
21560 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
21570 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
21580 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
21590 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
215a0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
215b0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
215c0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
215d0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
215e0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
215f0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
21600 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
21610 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
21620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21630 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
21640 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
21650 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21660 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21670 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
21680 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65  hen the .** more
21690 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
216a0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
216b0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
216c0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
216d0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
216e0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
216f0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
21700 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
21710 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32  NTS:.**.** {F132
21720 30 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72 65  02}  If [prepare
21730 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
21740 73 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a 2a  s ready to be.**
21750 20 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c 20             run, 
21760 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  then [sqlite3_st
21770 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20  ep(S)] advances 
21780 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74  that prepared st
21790 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  atement.**      
217a0 20 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63 6f       until to co
217b0 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69  mpletion or unti
217c0 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  l it is ready to
217d0 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 0a   return another.
217e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 77  **           row
217f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
21800 65 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75  et or an interru
21810 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65  pt or run-time e
21820 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
21830 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68 65  ** {F15304}  Whe
21840 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
21850 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
21860 75 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20  uses the .**    
21870 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
21880 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f   statement] S to
21890 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
218a0 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on,.**          
218b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
218c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f  turns [SQLITE_DO
218d0 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  NE]..**.** {F153
218e0 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c  06}  When a call
218f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
21900 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61  p(S)] stops beca
21910 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79 0a  use it is ready.
21920 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
21930 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72  return another r
21940 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
21950 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73   set, it returns
21960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
21970 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a  QLITE_ROW]..**.*
21980 2a 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20 61  * {F15308}  If a
21990 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
219a0 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75  3_step(S)] encou
219b0 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20  nters an.**     
219c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69        [sqlite3_i
219d0 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75  nterrupt|interru
219e0 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d  pt] or a run-tim
219f0 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20  e error,.**     
21a00 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73        it returns
21a10 20 61 6e 20 61 70 70 72 6f 70 72 61 69 74 65 20   an appropraite 
21a20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20  error code that 
21a30 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a  is not one of.**
21a40 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
21a50 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f  TE_OK], [SQLITE_
21a60 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROW], or [SQLITE
21a70 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DONE]..**.** {F
21a80 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73  15310}  If an [s
21a90 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
21aa0 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 72  |interrupt] or r
21ab0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
21ac0 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
21ad0 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
21ae0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
21af0 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
21b00 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
21b10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
21b20 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
21b30 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
21b40 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
21b50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21b60 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
21b70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21b80 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20 66  16()] then the f
21b90 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
21ba0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
21bb0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
21bc0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  R], [SQLITE_BUSY
21bd0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
21be0 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  SUSE]..*/.int sq
21bf0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
21c00 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
21c10 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
21c20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
21c30 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 46   a result set {F
21c40 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  13770}.**.** Ret
21c50 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
21c60 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  f values in the 
21c70 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
21c80 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a  he result set..*
21c90 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21ca0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20  .**.** {F13771} 
21cb0 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f   After a call to
21cc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
21cd0 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 0a  )] that returns.
21ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
21cf0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 5b  LITE_ROW], the [
21d00 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
21d10 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a 2a  nt(S)] routine.*
21d20 2a 20 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  *           will
21d30 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
21d40 20 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a 2a   value as the.**
21d50 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
21d60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
21d70 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  (S)] function..*
21d80 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20 41  *.** {F13772}  A
21d90 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
21da0 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72  ep(S)] has retur
21db0 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  ned any value ot
21dc0 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
21dd0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
21de0 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71  W] or before [sq
21df0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
21e00 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20 20  as been .**     
21e10 20 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e 20        called on 
21e20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
21e30 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20  atement] for.** 
21e40 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 69            the fi
21e50 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69  rst time since i
21e60 74 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f 70  t was [sqlite3_p
21e70 72 65 70 61 72 65 7c 70 72 65 70 61 72 65 64 5d  repare|prepared]
21e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
21e90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 7c   [sqlite3_reset|
21ea0 72 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71 6c  reset], the [sql
21eb0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
21ec0 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
21ed0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21ee0 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
21ef0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
21f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
21f10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
21f20 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
21f30 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46  tal Datatypes {F
21f40 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10265}.** KEYWOR
21f50 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
21f60 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76  **.** {F10266}Ev
21f70 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
21f80 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
21f90 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
21fa0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
21fb0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
21fc0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
21fd0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
21fe0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
21ff0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
22000 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
22010 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
22020 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20  > NULL.** </ul> 
22030 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
22040 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
22050 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
22060 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
22070 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
22080 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
22090 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
220a0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
220b0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
220c0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
220d0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
220e0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
220f0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
22100 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
22110 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
22120 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
22130 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
22140 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  EXT not.** SQLIT
22150 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
22160 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
22170 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
22180 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
22190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
221a0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
221b0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
221c0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
221d0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
221e0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
221f0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
22200 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
22210 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
22220 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
22230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
22240 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f  sults Values Fro
22250 6d 20 41 20 51 75 65 72 79 20 7b 46 31 33 38 30  m A Query {F1380
22260 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
22270 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
22280 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65   "result set que
22290 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ry" interface..*
222a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
222b0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
222c0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20  mation about.** 
222d0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
222e0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  of the current r
222f0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
22300 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a  uery.  In every.
22310 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ** case the firs
22320 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
22330 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a  pointer to the .
22340 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
22350 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
22360 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74  being.** evaluat
22370 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
22380 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73  _stmt*] that was
22390 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a   returned from .
223a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
223b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
223c0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
223d0 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63  ) and.** the sec
223e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
223f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
22400 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
22410 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a  h information .*
22420 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
22430 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d  rned.  The left-
22440 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
22450 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a  he result set.**
22460 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
22470 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
22480 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
22490 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
224a0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
224b0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
224c0 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e  ** the column in
224d0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
224e0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
224f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a  is undefined. .*
22500 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22510 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
22520 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
22530 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
22540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
22550 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
22560 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
22570 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
22580 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22590 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
225a0 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65  alize()] has bee
225b0 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  n call subsequen
225c0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
225d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
225e0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
225f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
22600 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
22610 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
22620 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
22630 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
22640 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
22650 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
22660 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
22670 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22680 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
22690 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
226a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
226b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
226c0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
226d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
226e0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
226f0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
22700 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
22710 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
22720 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
22730 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a  e undefined.  .*
22740 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
22750 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
22760 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a  outine returns .
22770 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
22780 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
22790 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
227a0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
227b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
227c0 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
227d0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
227e0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
227f0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
22800 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
22810 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
22820 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
22830 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
22840 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
22850 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
22860 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
22870 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
22880 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
22890 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
228a0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
228b0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
228c0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
228d0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
228e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
228f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
22900 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
22910 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
22920 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
22930 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
22940 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
22950 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
22960 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
22970 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
22980 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
22990 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
229a0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
229b0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
229c0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a  lumn_bytes() .**
229d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
229e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
229f0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
22a00 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
22a10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
22a20 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
22a30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
22a40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
22a50 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
22a60 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
22a70 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
22a80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
22a90 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  es..** If the re
22aa0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
22ab0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
22ac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
22ad0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
22ae0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
22af0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
22b00 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
22b10 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
22b20 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
22b30 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
22b40 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54  hat string..** T
22b50 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
22b60 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
22b70 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
22b80 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
22b90 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
22ba0 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79  ng.  For clarity
22bb0 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  : the value retu
22bc0 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62  rned is the numb
22bd0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
22be0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
22bf0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
22c00 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
22c10 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e  * Strings return
22c20 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
22c30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
22c40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22c50 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
22c60 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
22c70 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
22c80 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
22c90 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
22ca0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
22cb0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
22cc0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c  a zero-length bl
22cd0 6f 62 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  ob is an arbitra
22ce0 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70  ry.** pointer, p
22cf0 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e  ossibly even a N
22d00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
22d10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
22d20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
22d30 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
22d40 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ar to sqlite3_co
22d50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
22d60 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72  but leaves the r
22d70 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20  esult in UTF-16 
22d80 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
22d90 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
22da0 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20  UTF-8.  .** The 
22db0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
22dc0 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
22dd0 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
22de0 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
22df0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
22e00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
22e10 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
22e20 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
22e30 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
22e40 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
22e50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
22e60 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
22e70 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
22e80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
22e90 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
22ea0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
22eb0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
22ec0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22ed0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
22ee0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
22ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22f00 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
22f10 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
22f20 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
22f30 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
22f40 65 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c  es like .** [sql
22f50 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
22f60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
22f70 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 20 5b 73  e_text()], or [s
22f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
22f90 65 73 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  es()],.** then t
22fa0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
22fb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
22fc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
22fd0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
22fe0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
22ff0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
23000 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
23010 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
23020 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
23030 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
23040 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
23050 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
23060 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
23070 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
23080 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e  ly to do the con
23090 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d  version.** autom
230a0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66  atically.  The f
230b0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
230c0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
230d0 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61  rsions that.** a
230e0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
230f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
23100 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
23110 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
23120 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
23130 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
23140 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
23150 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
23160 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
23170 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
23180 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
23190 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
231a0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
231b0 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
231c0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
231d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
231e0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
231f0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
23200 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
23210 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
23220 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
23230 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
23240 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
23250 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
23260 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
23270 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
23280 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
23290 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
232a0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
232b0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
232c0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
232d0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
232e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
232f0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
23300 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54   Same as for INT
23310 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
23320 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
23330 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
23340 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
23350 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
23360 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
23370 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
23380 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
23390 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
233a0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
233b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
233c0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
233d0 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
233e0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
233f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
23400 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
23410 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
23420 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
23430 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
23440 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
23450 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23460 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
23470 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
23480 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
23490 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
234a0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
234b0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
234c0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
234d0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
234e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
234f0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
23500 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
23510 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
23520 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
23530 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
23540 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
23550 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
23560 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
23570 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
23580 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
23590 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
235a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
235b0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
235c0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
235d0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
235e0 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
235f0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
23600 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
23610 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69 6e  on equavalent in
23620 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
23630 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
23640 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
23650 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
23660 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
23670 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
23680 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
23690 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
236a0 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
236b0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
236c0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
236d0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
236e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
236f0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
23700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23710 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
23720 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
23730 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
23740 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
23750 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
23760 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  d. .** Type conv
23770 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
23780 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
23790 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
237a0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
237b0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
237c0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  ul>.** <li><p>  
237d0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
237e0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
237f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
23800 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20  _text() .**     
23810 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f       or sqlite3_
23820 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
23830 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
23840 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
23850 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ght.**          
23860 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
23870 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
23880 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  /p></li>.**.** <
23890 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
238a0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
238b0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
238c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
238d0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
238e0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
238f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
23900 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
23910 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
23920 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
23930 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
23940 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  p></li>.**.** <l
23950 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
23960 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
23970 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
23980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23990 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
239a0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
239b0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
239c0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
239d0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
239e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
239f0 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c  to UTF-8.</p></l
23a00 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
23a10 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65  * Conversions be
23a20 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
23a30 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
23a40 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
23a50 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
23a60 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
23a70 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
23a80 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
23a90 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
23aa0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
23ab0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
23ac0 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69  ter points to wi
23ad0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
23ae0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
23af0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
23b00 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
23b10 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
23b20 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
23b30 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a  sometime it is.*
23b40 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  * not possible a
23b50 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
23b60 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
23b70 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
23b80 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  .  .**.** The sa
23b90 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
23ba0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
23bb0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
23bc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
23bd0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
23be0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
23bf0 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20  .**.**  <ul>.** 
23c00 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
23c10 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
23c20 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
23c30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
23c40 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
23c50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
23c60 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
23c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23c80 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
23c90 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
23ca0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
23cb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23cc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
23cd0 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a  i>.**  </ul>.**.
23ce0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
23cf0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
23d00 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
23d10 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  n_text(), sqlite
23d20 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
23d30 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
23d40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
23d50 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
23d60 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68  e result into th
23d70 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72  e desired.** for
23d80 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
23d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23da0 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74  bytes() or sqlit
23db0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23dc0 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74  6() to.** find t
23dd0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
23de0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
23df0 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ix call to sqlit
23e00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
23e10 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
23e20 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
23e30 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
23e40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23e50 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74  6().  And do not
23e60 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  .** mix calls to
23e70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23e80 74 65 78 74 31 36 28 29 20 77 69 74 68 20 63 61  text16() with ca
23e90 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
23ea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
23eb0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
23ec0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
23ed0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
23ee0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
23ef0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
23f00 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
23f10 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
23f20 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
23f30 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
23f40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23f50 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
23f60 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63   The memory spac
23f70 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
23f80 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c  trings.** and bl
23f90 6f 62 73 20 69 73 20 66 72 65 65 64 20 61 75 74  obs is freed aut
23fa0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
23fb0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
23fc0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
23fd0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
23fe0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
23ff0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
24000 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
24010 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  into .** [sqlite
24020 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
24030 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
24040 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
24050 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
24060 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
24070 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
24080 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
24090 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
240a0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
240b0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
240c0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
240d0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
240e0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
240f0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
24100 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
24110 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
24120 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
24130 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
24140 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
24150 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
24160 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33  S:.**.** {F13803
24170 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24180 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
24190 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
241a0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
241b0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
241c0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
241d0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
241e0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
241f0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24200 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
24210 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20  a blob and then 
24220 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
24230 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
24240 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76   the converted v
24250 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  alue..**.** {F13
24260 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  806} The [sqlite
24270 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53  3_column_bytes(S
24280 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24290 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
242a0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
242b0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c   bytes in the bl
242c0 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  ob or string (ex
242d0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
242e0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
242f0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
24300 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
24310 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
24320 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
24330 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
24340 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
24350 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72  mn_blob(S,N)] or
24360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24380 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  t(S,N)]..**.** {
24390 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c  F13809} The [sql
243a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
243b0 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  s16(S,N)] interf
243c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
243d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
243e0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
243f0 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
24400 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
24410 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
24420 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
24430 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
24440 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
24450 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
24460 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
24470 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24480 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a  text16(S,N)]..**
24490 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65  .** {F13812} The
244a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
244b0 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e  _double(S,N)] in
244c0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
244d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
244e0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
244f0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
24500 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
24510 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
24520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24530 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
24540 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
24550 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
24560 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
24570 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
24580 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d  ..**.** {F13815}
24590 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
245a0 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
245b0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
245c0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
245d0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
245e0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
245f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24600 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24610 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24620 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
24630 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
24640 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
24650 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68        returns th
24660 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20  e lower 32 bits 
24670 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
24680 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20  .**.** {F13818} 
24690 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
246a0 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20  umn_int64(S,N)] 
246b0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
246c0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
246d0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
246e0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
246f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
24700 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
24710 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24720 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
24730 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
24740 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
24750 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
24760 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
24770 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
24780 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3821} The [sqlit
24790 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
247a0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
247b0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
247c0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
247d0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
247e0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
247f0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
24800 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
24810 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
24820 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
24830 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20  nated UTF-8 .** 
24840 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
24850 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
24860 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
24870 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
24880 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  824} The [sqlite
24890 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
248a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
248b0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
248c0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
248d0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
248e0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
248f0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
24900 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
24910 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24920 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
24930 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
24940 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
24950 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
24960 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
24970 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
24980 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
24990 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
249a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  ng..**.** {F1382
249b0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
249c0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29  column_type(S,N)
249d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
249e0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
249f0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
24a00 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
24a10 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
24a20 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
24a30 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
24a40 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
24a50 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
24a60 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
24a70 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d     the Nth colum
24a80 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
24a90 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
24aa0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
24ab0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
24ac0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
24ad0 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54 68  *.** {F13830} Th
24ae0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24af0 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e  n_value(S,N)] in
24b00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24b10 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
24b20 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70  inter to an [unp
24b30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24b40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
24b50 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
24b60 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
24b70 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
24b80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
24b90 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
24ba0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24bb0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f  tement] S..*/.co
24bc0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24bd0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
24be0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24bf0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
24c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24c10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24c20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
24c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24c40 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
24c50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24c60 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
24c70 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
24c80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24c90 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
24ca0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
24cb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24cc0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
24cd0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
24ce0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
24cf0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24d00 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
24d10 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
24d20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
24d30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24d40 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
24d50 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24d60 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
24d70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24d80 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
24d90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
24da0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24db0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
24dc0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
24dd0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
24de0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24df0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
24e00 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
24e10 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
24e20 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 30 30  t Object {F13300
24e30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
24e40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
24e50 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
24e60 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a  d to delete a .*
24e70 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24e80 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73  ement]. If the s
24e90 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
24ea0 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
24eb0 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78  fully, or not ex
24ec0 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
24ed0 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  hen SQLITE_OK is
24ee0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
24ef0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
24f00 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
24f10 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b  ed then an .** [
24f20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
24f30 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
24f40 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
24f50 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ned. .**.** This
24f60 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
24f70 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
24f80 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
24f90 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
24fa0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
24fb0 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65  tement].  If the
24fc0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
24fd0 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d   has not .** com
24fe0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
24ff0 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
25000 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
25010 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
25020 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
25030 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  ror or an interr
25040 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69  upt.  (See [sqli
25050 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
25060 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  .) .** Incomplet
25070 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
25080 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
25090 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
250a0 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65  ncelled,  .** de
250b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
250c0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
250d0 64 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72  d the .** [error
250e0 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
250f0 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
25100 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ABORT]..**.** IN
25110 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
25120 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71  {F11302} The [sq
25130 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
25140 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
25150 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20  troys the.**    
25160 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
25170 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64  statement] S and
25180 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a   releases all.**
25190 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
251a0 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72   and file resour
251b0 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74  ces held by that
251c0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b   object..**.** {
251d0 46 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d  F11304} If the m
251e0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
251f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
25200 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
25210 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
25220 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25230 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f  returned an erro
25240 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
25250 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  hen [sqlite3_fin
25260 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e  alize(S)] return
25270 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f  s that same erro
25280 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
25290 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
252a0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
252b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
252c0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
252d0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
252e0 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a  ect {F13330}.**.
252f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
25300 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
25310 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
25320 65 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72  et a .** [prepar
25330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
25340 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f  ject..** back to
25350 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
25360 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
25370 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
25380 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
25390 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
253a0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
253b0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
253c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
253d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
253e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
253f0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
25400 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
25410 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
25420 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
25430 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
25440 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54  **.** {F11332} T
25450 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
25460 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
25470 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
25480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25490 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
254a0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
254b0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
254c0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  am..**.** {F1133
254d0 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
254e0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
254f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25500 66 6f 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  for .**         
25510 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25520 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
25530 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
25540 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
25550 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
25560 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
25570 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
25580 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
25590 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20   on S,.**       
255a0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
255b0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
255c0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
255d0 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49  **.** {F11336} I
255e0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
255f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
25600 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 0a  e3_step(S)] for.
25610 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
25620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25630 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
25640 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  error, then.**  
25650 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25660 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
25670 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
25680 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
25690 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54  **.** {F11338} T
256a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
256b0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
256c0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
256d0 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  the values.**   
256e0 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73         of any [s
256f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25700 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70  |bindings] on [p
25710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25720 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
25730 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
25740 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
25750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25760 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
25770 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
25780 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b  ns {F16100}.** K
25790 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
257a0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
257b0 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ines} .**.** The
257c0 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
257d0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
257e0 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63  nown as.** "func
257f0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
25800 75 74 69 6e 65 73 22 29 20 61 72 65 20 75 73 65  utines") are use
25810 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
25820 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
25830 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65  ates.** or to re
25840 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
25850 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20  ior of existing 
25860 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
25870 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
25880 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20  e.** difference 
25890 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65  only between the
258a0 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
258b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
258c0 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f  r, the.** name o
258d0 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66  f the (scalar) f
258e0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
258f0 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
25900 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   in UTF-8 for.**
25910 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
25920 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55  function() and U
25930 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65  TF-16 for sqlite
25940 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25950 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
25960 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
25970 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
25980 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
25990 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
259a0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
259b0 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61   be added.  If a
259c0 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72   single.** progr
259d0 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  am uses more tha
259e0 6e 20 6f 6e 65 20 5b 64 61 74 61 62 61 73 65 20  n one [database 
259f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 65  connection] inte
25a00 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
25a10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  .** functions mu
25a20 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
25a30 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68  vidually to each
25a40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25a50 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ction]..**.** Th
25a60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
25a70 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
25a80 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
25a90 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
25aa0 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64  .** or redefined
25ab0 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20  ..** The length 
25ac0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
25ad0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
25ae0 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
25af0 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74  f the .** zero-t
25b00 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
25b10 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
25b20 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
25b30 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
25b40 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
25b50 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
25b60 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
25b70 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
25b80 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
25b90 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  in an SQLITE_ERR
25ba0 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  OR error..**.** 
25bb0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
25bc0 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ter is the numbe
25bd0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
25be0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
25bf0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
25c00 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
25c10 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
25c20 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
25c30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25c40 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
25c50 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
25c60 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25c70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
25c80 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
25c90 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
25ca0 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c  es what .** [SQL
25cb0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
25cc0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
25cd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
25ce0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
25cf0 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
25d00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
25d10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
25d20 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
25d30 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
25d40 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
25d50 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
25d60 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
25d70 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
25d80 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
25d90 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
25da0 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
25db0 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
25dc0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
25dd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25de0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
25df0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25e00 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
25e10 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
25e20 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
25e30 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
25e40 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
25e50 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
25e60 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
25e70 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
25e80 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
25e90 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
25ea0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
25eb0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
25ec0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
25ed0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
25ee0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
25ef0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
25f00 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
25f10 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
25f20 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a   not care what.*
25f30 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  * text encoding 
25f40 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
25f50 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
25f60 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b  t should be.** [
25f70 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
25f80 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
25f90 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
25fa0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
25fb0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
25fc0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75  ion.** of the fu
25fd0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
25fe0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
25ff0 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20  ointer using.** 
26000 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
26010 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
26020 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
26030 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
26040 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
26050 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
26060 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
26070 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
26080 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
26090 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a  lement the SQL.*
260a0 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  * function or ag
260b0 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
260c0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
260d0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
260e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mentation of.** 
260f0 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61  the xFunc callba
26100 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
26110 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
26120 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
26130 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
26140 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  al parameters. A
26150 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
26160 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
26170 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
26180 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20  ion.** of xStep 
26190 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
261a0 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
261b0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
261c0 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20  To delete an.** 
261d0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
261e0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
261f0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
26200 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
26210 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
26220 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
26230 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
26240 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
26250 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
26260 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
26270 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
26280 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
26290 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
262a0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
262b0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
262c0 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65  ffering perferre
262d0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
262e0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
262f0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
26300 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
26310 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
26320 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
26330 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
26340 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
26350 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
26360 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65  .** {F16103} The
26370 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26380 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69  _function16()] i
26390 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73  nterface behaves
263a0 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
263b0 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74       like [sqlit
263c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
263d0 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77  on()] in every w
263e0 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ay except that i
263f0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
26400 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75  terprets the zFu
26410 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d  nctionName argum
26420 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20 20 20  ent as.**       
26430 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
26440 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
26450 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
26460 65 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20  ead of as a.**  
26470 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
26480 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a  minated UTF-8..*
26490 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41 20  *.** {F16106} A 
264a0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
264b0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20  ation of.**     
264c0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
264d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
264e0 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20  n(D,X,N,E,...)] 
264f0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
26500 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
26510 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c  or replaces call
26520 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69  back functions i
26530 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
26540 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20  ection] D.**    
26550 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d        used to im
26560 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
26570 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58  function named X
26580 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65   with N paramete
26590 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rs.**          a
265a0 6e 64 20 68 61 76 69 6e 67 20 61 20 70 65 72 66  nd having a perf
265b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
265c0 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20  ing of E..**.** 
265d0 7b 46 31 36 31 30 39 7d 20 41 20 73 75 63 63 65  {F16109} A succe
265e0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
265f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26600 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
26610 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20  ,F,S,L)].**     
26620 20 20 20 20 20 72 65 70 6c 61 63 65 73 20 74 68       replaces th
26630 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c  e P, F, S, and L
26640 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79   values from any
26650 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
26660 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
26670 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20  e same D, X, N, 
26680 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a  and E values..**
26690 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54 68 65  .** {F16112} The
266a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
266b0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e  _function(D,X,..
266c0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
266d0 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ils with.**     
266e0 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f       a return co
266f0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52  de of [SQLITE_ER
26700 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20  ROR] if the SQL 
26710 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20  function name X 
26720 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  is.**          l
26730 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62  onger than 255 b
26740 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f  ytes exclusive o
26750 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  f the zero termi
26760 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nator..**.** {F1
26770 36 31 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d  6118} Either F m
26780 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20  ust be NULL and 
26790 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d  S and L are non-
267a0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a  NULL or else F.*
267b0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
267c0 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  n-NULL and S and
267d0 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68   L are NULL, oth
267e0 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20  erwise.**       
267f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
26800 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
26810 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65  N,E,P,F,S,L)] re
26820 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52  turns [SQLITE_ER
26830 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ROR]..**.** {F16
26840 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
26850 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26860 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  n(D,...)] interf
26870 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
26880 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
26890 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
268a0 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65  ITE_BUSY] if the
268b0 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61 72  re exist [prepar
268c0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
268d0 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63  *          assoc
268e0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
268f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26900 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
26910 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16124} The [sqli
26920 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26930 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20  ion(D,X,N,...)] 
26940 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
26950 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
26960 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
26970 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  f [SQLITE_ERROR]
26980 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20   if parameter N 
26990 28 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20  (specifying the 
269a0 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
269b0 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20     of arguments 
269c0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
269d0 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74  ion being regist
269e0 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a  ered) is less.**
269f0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d            than -
26a00 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
26a10 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  n 127..**.** {F1
26a20 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20  6127} When N is 
26a30 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
26a40 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
26a50 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
26a60 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
26a70 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75     interface cau
26a80 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ses callbacks to
26a90 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
26aa0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
26ac0 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75  ed X when the nu
26ad0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
26ae0 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
26af0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ction is.**     
26b00 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a       exactly N..
26b10 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57  **.** {F16130} W
26b20 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65  hen N is -1, the
26b30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26b40 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
26b50 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
26b60 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73    interface caus
26b70 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  es callbacks to 
26b80 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
26b90 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
26ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
26bb0 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d  d X with any num
26bc0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
26bd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d  ..**.** {F16133}
26be0 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b   When calls to [
26bf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26c00 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
26c10 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
26c20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65  specify multiple
26c30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
26c40 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
26c50 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20  ction X.**      
26c60 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65      and when one
26c70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26c80 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65  has N>=0 and the
26c90 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31   other has N=(-1
26ca0 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ).**          th
26cb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
26cc0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
26cd0 20 4e 20 69 73 20 70 72 65 66 65 72 72 65 64 2e   N is preferred.
26ce0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20  .**.** {F16136} 
26cf0 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  When calls to [s
26d00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26d10 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
26d20 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
26d30 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
26d40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
26d50 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
26d60 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a  nction X with.**
26d70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
26d80 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  me number of arg
26d90 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74  uments N but wit
26da0 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20  h different.**  
26db0 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67          encoding
26dc0 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d  s E, then the im
26dd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
26de0 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65  re E matches the
26df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
26e00 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
26e10 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a  s preferred..**.
26e20 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f 72 20  ** {F16139} For 
26e30 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  an aggregate SQL
26e40 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65   function create
26e50 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
26e60 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
26e70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
26e80 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74  ,N,E,P,0,S,L)] t
26e90 68 65 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a  he finializer.**
26ea0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
26eb0 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73  on L will always
26ec0 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   be invoked exac
26ed0 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a  tly once if the.
26ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70  **          step
26ef0 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63   function S is c
26f00 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
26f10 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  e times..**.** {
26f20 46 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c  F16142} When SQL
26f30 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68  ite invokes eith
26f40 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  er the xFunc or 
26f50 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f  xStep function o
26f60 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  f.**          an
26f70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26f80 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
26f90 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63  n or aggregate c
26fa0 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  reated.**       
26fb0 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
26fc0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
26fd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72  ] or [sqlite3_cr
26fe0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
26ff0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
27000 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f  then the array o
27010 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
27020 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64  ] objects passed
27030 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
27040 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65      third parame
27050 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b  ter are always [
27060 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27070 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
27080 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27090 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
270a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
270b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
270c0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
270d0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
270e0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
270f0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
27100 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
27110 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
27120 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
27130 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
27140 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27150 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
27160 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
27170 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
27180 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
27190 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
271a0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
271b0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
271c0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
271d0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
271e0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
271f0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
27200 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
27210 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27220 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
27230 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
27240 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
27250 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
27260 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
27270 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
27280 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27290 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
272a0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
272b0 69 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a  ings {F10267}.**
272c0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
272d0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
272e0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
272f0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
27300 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
27310 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
27320 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
27330 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
27340 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
27350 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
27360 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
27370 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
27380 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
27390 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
273a0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
273b0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
273c0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
273d0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
273e0 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
273f0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
27400 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
27410 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
27420 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
27430 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
27440 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27450 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
27460 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65  CAPI3REF: Obsole
27470 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  te Functions.**.
27480 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
27490 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f  ns are all now o
274a0 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64  bsolete.  In ord
274b0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
274c0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
274d0 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
274e0 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f  lder code, we co
274f0 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72  ntinue to suppor
27500 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  t.** these funct
27510 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  ions.  However, 
27520 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20  new development 
27530 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20  projects should 
27540 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
27550 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
27560 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
27570 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
27580 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
27590 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
275a0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
275b0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
275c0 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  ant they do..*/.
275d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
275e0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
275f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69  te3_context*);.i
27600 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
27610 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
27620 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  );.int sqlite3_t
27630 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
27640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
27660 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
27670 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
27680 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  ;.void sqlite3_t
27690 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
276a0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
276b0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
276c0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
276d0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
276e0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
276f0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
27700 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
27710 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
27720 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 46  ameter Values {F
27730 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  15100}.**.** The
27740 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
27750 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
27760 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
27770 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
27780 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
27790 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
277a0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
277b0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
277c0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
277d0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
277e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
277f0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
27800 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
27810 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
27820 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
27830 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
27840 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
27850 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
27860 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
27870 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
27880 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
27890 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
278a0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
278b0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
278c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
278d0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
278e0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
278f0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
27900 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27910 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
27920 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
27930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27940 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
27950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
27960 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
27970 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27980 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
27990 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
279a0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
279b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
279c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
279d0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
279e0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
279f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27a00 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
27a10 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
27a20 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
27a30 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
27a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
27a50 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
27a60 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
27a70 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  avior..**.** The
27a80 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
27a90 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
27aa0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a  orresponding .**
27ab0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27ac0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
27ad0 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65  column_* routine
27ae0 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 0a  s] except that .
27af0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
27b00 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
27b10 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
27b20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27b30 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74   pointer.** inst
27b40 65 61 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ead of an [sqlit
27b50 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
27b60 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
27b70 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
27b80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27b90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
27ba0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
27bb0 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72 69  cts a UTF16 stri
27bc0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
27bd0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
27be0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
27bf0 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
27c00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27c10 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
27c20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
27c30 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
27c40 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73 74  extract UTF16 st
27c50 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
27c60 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
27c70 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
27c80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
27c90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
27ca0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
27cb0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
27cc0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
27cd0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
27ce0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
27cf0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
27d00 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
27d10 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
27d20 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
27d30 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
27d40 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
27d50 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
27d60 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
27d70 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
27d80 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
27d90 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65  .** words if the
27da0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
27db0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
27dc0 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
27dd0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
27de0 69 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74  ion is done.  Ot
27df0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
27e00 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54  rsion occurs.  T
27e10 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  he .** [SQLITE_I
27e20 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
27e30 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
27e40 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
27e50 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
27e60 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
27e70 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
27e80 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
27e90 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72  ter that.** is r
27ea0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
27eb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
27ec0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
27ed0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
27ee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
27ef0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
27f00 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
27f10 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
27f20 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
27f30 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
27f40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
27f50 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
27f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27f70 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
27f80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27f90 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  6()].  .**.** Th
27fa0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
27fb0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
27fc0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
27fd0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
27fe0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
27ff0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
28000 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
28010 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20  eters..**.**.** 
28020 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
28030 2a 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b  * {F15103} The [
28040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
28050 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  ob(V)] interface
28060 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28070 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
28080 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28090 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
280a0 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65  o a blob and the
280b0 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  n returns a.**  
280c0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
280d0 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
280e0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
280f0 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  15106} The [sqli
28100 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
28110 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
28120 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
28130 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
28140 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f  bytes in the blo
28150 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  b or string (exc
28160 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
28170 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
28180 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
28190 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
281a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
281b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
281c0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
281d0 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
281e0 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20  _blob(V)] or.** 
281f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
28200 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
28210 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d  ..**.** {F15109}
28220 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28230 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20  lue_bytes16(V)] 
28240 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28250 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28260 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
28270 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
28280 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
28290 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
282a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
282b0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
282c0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
282d0 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
282e0 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
282f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
28300 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c  alue_text16(V)],
28310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
28320 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28330 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71  16be(V)], or [sq
28340 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28350 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16le(V)]..**.** 
28360 7b 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71  {F15112} The [sq
28370 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
28380 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
28390 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
283a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
283b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
283c0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
283d0 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
283e0 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
283f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
28400 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
28410 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
28420 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  5115} The [sqlit
28430 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d  e3_value_int(V)]
28440 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
28450 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
28460 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
28470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28480 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
28490 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
284a0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
284b0 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
284c0 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
284d0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
284e0 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68  *.** {F15118} Th
284f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28500 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72  _int64(V)] inter
28510 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
28520 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
28530 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28540 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
28550 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
28560 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
28570 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
28580 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
28590 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
285a0 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68 65  .** {F15121} The
285b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
285c0 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61  text(V)] interfa
285d0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
285e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
285f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28600 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
28610 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
28620 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20  nated UTF-8 .** 
28630 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
28640 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
28650 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
28660 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ring..**.** {F15
28670 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
28680 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
28690 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
286a0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
286b0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
286c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
286d0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
286e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
286f0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
28700 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
28710 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
28720 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
28730 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
28740 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
28750 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
28760 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20  ** {F15127} The 
28770 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28780 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65  ext16be(V)] inte
28790 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
287a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
287b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
287c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
287d0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
287e0 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
287f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
28800 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65  ned UTF-16 big-e
28810 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
28820 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
28830 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28840 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
28850 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68  *.** {F15130} Th
28860 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28870 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e  _text16le(V)] in
28880 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
28890 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
288a0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
288b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
288c0 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
288d0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
288e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
288f0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74  igned UTF-16 lit
28900 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  tle-endian.**   
28910 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
28920 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
28930 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
28940 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33  ng..**.** {F1513
28950 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
28960 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69  value_type(V)] i
28970 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65  .**          one
28990 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
289a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ], [SQLITE_INTEG
289b0 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
289c0 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AT],.**         
289d0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
289e0 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  or [SQLITE_BLOB]
289f0 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
28a00 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
28a10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
28a20 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a  ue] object V..**
28a30 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65  .** {F15136} The
28a40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28a50 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d  numeric_type(V)]
28a60 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
28a70 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rts.**          
28a80 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  the [protected s
28a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28aa0 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68  ject V into eith
28ab0 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  er an integer or
28ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
28ad0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
28ae0 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f  lue if it can do
28af0 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73   so without loss
28b00 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
28b10 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64  information, and
28b20 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20   returns one of 
28b30 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a  [SQLITE_NULL],.*
28b40 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
28b50 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
28b60 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
28b70 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a  LITE_TEXT], or.*
28b80 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
28b90 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
28ba0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
28bb0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f          the [pro
28bc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28bd0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61  alue] object V a
28be0 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73  fter the convers
28bf0 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a  ion attempt..*/.
28c00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28c10 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
28c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28c40 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
28c50 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
28c60 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
28c70 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
28c80 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
28c90 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
28ca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28cb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
28cc0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
28cd0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
28ce0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
28cf0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
28d00 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
28d10 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
28d20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28d30 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
28d40 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
28d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28d60 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
28d70 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
28d80 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
28d90 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
28da0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
28db0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
28dc0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
28dd0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
28de0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
28df0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
28e00 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
28e10 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
28e20 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
28e30 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
28e40 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
28e50 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
28e60 20 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30   Context {F16210
28e70 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  }.**.** The impl
28e80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
28e90 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
28ea0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
28eb0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
28ec0 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
28ed0 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
28ee0 65 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20  eir state.  .** 
28ef0 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
28f00 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
28f10 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72  gate_context() r
28f20 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20  outine is.** is 
28f30 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72  called for a par
28f40 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
28f50 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61  e, SQLite alloca
28f60 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65  tes nBytes of me
28f70 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68  mory.** zeros th
28f80 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
28f90 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
28fa0 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65   to it..** On se
28fb0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
28fc0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ent calls to sql
28fd0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28fe0 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20  ontext().** for 
28ff0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
29000 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65  te function inde
29010 78 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  x, the same buff
29020 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
29030 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
29040 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
29050 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
29060 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  e the returned b
29070 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
29080 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  ate data..**.** 
29090 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
290a0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61  ally frees the a
290b0 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20  llocated buffer 
290c0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
290d0 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63  te.** query conc
290e0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
290f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
29100 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70   should be a cop
29110 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71  y of the .** [sq
29120 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
29130 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
29140 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
29150 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
29160 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
29170 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
29180 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
29190 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
291a0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
291b0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
291c0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
291d0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
291e0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
291f0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
29200 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
29210 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
29220 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  TS:.**.** {F1621
29230 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76  1} The first inv
29240 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
29250 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29260 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a  ntext(C,N)] for.
29270 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61  **          a pa
29280 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
29290 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74  e of an aggregat
292a0 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20  e function (for 
292b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
292c0 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
292d0 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74   C) causes SQLit
292e0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
292f0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
29300 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  y,.**          z
29310 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ero that memory,
29320 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
29330 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c  inter to the all
29340 6f 63 61 74 69 6f 6e 65 64 0a 2a 2a 20 20 20 20  ocationed.**    
29350 20 20 20 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a        memory..**
29360 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66 20  .** {F16213} If 
29370 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
29380 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
29390 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   during.**      
293a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67      [sqlite3_agg
293b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
293c0 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75  ,N)] then the fu
293d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
293e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35 7d  ..**.** {F16215}
293f0 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   Second and subs
29400 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
29410 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ns of.**        
29420 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65    [sqlite3_aggre
29430 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
29440 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  )] for the same 
29450 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
29460 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67  C.**          ig
29470 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d  nore the N param
29480 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20  eter and return 
29490 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
294a0 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
294b0 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72    block of memor
294c0 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  y returned by th
294d0 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69  e first invocati
294e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  on..**.** {F1621
294f0 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  7} The memory al
29500 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69  located by [sqli
29510 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29520 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a  ntext(C,N)] is.*
29530 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
29540 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f  atically freed o
29550 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  n the next call 
29560 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
29570 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
29580 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
29590 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65  alize()] for the
295a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
295b0 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67  ment] containing
295c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
295d0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
295e0 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
295f0 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a  ith context C..*
29600 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
29610 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
29620 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
29630 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
29640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29650 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
29660 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 34  Functions {F1624
29670 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
29680 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
29690 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
296a0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
296b0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
296c0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
296d0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
296e0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
296f0 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b  .** of the the [
29700 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29710 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
29720 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
29730 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
29740 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
29750 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
29760 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
29770 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
29780 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a  unction. {END}.*
29790 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
297a0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
297b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
297c0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
297d0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
297e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
297f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
29800 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
29810 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33 7d 20  .**.** {F16243} 
29820 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  The [sqlite3_use
29830 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72  r_data(C)] inter
29840 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
29850 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
29860 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72         P pointer
29870 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
29880 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29890 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
298a0 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
298b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
298c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44  ate_function16(D
298d0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
298e0 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20   call that.**   
298f0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
29900 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
29910 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
29920 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  th .**          
29930 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
29940 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ] C..*/.void *sq
29950 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
29960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29970 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29980 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
29990 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
299a0 74 69 6f 6e 73 20 7b 46 31 36 32 35 30 7d 0a 2a  tions {F16250}.*
299b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
299c0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
299d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
299e0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
299f0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
29a00 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
29a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
29a20 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
29a30 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b  .** of the the [
29a40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29a50 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
29a60 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
29a70 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
29a80 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
29a90 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
29aa0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
29ab0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
29ac0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
29ad0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
29ae0 20 7b 46 31 36 32 35 33 7d 20 54 68 65 20 5b 73   {F16253} The [s
29af0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
29b00 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74  b_handle(C)] int
29b10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29b20 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
29b30 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74           D point
29b40 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
29b50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29b60 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
29b70 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
29b80 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
29b90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29ba0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
29bb0 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
29bc0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
29bd0 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
29be0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
29bf0 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20  with .**        
29c00 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65    [sqlite3_conte
29c10 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65  xt] C..*/.sqlite
29c20 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
29c30 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
29c40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
29c50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29c60 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
29c70 61 72 79 20 44 61 74 61 20 7b 46 31 36 32 37 30  ary Data {F16270
29c80 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  }.**.** The foll
29c90 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
29ca0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
29cb0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
29cc0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
29cd0 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74  sociate meta-dat
29ce0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
29cf0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
29d00 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
29d10 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
29d20 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
29d30 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
29d40 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
29d50 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
29d60 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
29d70 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
29d80 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d  associated meta-
29d90 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
29da0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
29db0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
29dc0 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
29dd0 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
29de0 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
29df0 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
29e00 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
29e10 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
29e20 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
29e30 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
29e40 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63   meta-data assoc
29e50 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
29e60 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
29e70 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
29e80 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
29e90 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
29ea0 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
29eb0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
29ec0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
29ed0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
29ee0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
29ef0 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
29f00 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
29f10 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
29f20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
29f30 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
29f40 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
29f50 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29f60 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
29f70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29f80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
29f90 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61  e meta-data.** a
29fa0 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
29fb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
29fc0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
29fd0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
29fe0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
29ff0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
2a000 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a010 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74  on..** If no met
2a020 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  a-data has been 
2a030 65 76 65 72 20 62 65 65 6e 20 73 65 74 20 66 6f  ever been set fo
2a040 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67  r the Nth.** arg
2a050 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
2a060 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
2a070 20 63 6f 6f 72 65 73 70 6f 6e 64 69 6e 67 20 66   cooresponding f
2a080 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2a090 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e 67 65 64  r.** has changed
2a0a0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
2a0b0 64 61 74 61 20 77 61 73 20 73 65 74 2c 20 74 68  data was set, th
2a0c0 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
2a0d0 75 78 64 61 74 61 28 29 0a 2a 2a 20 72 65 74 75  uxdata().** retu
2a0e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2a0f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2a100 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2a110 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
2a120 76 65 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74  ves the meta-dat
2a130 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
2a140 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
2a150 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
2a160 2d 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  -data for the N-
2a170 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
2a180 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2a190 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a1a0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
2a1b0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2a1c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a1d0 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
2a1e0 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
2a1f0 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
2a200 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49  destroyed. .** I
2a210 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
2a220 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
2a230 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2a240 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  tor .** function
2a250 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2a260 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2a270 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a280 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2a290 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20 74 68  eta-data when th
2a2a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2a2b0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2a2c0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2a2d0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2a2e0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2a2f0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2a300 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2a310 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2a320 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2a330 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2a340 65 74 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61  eta-data on.** a
2a350 6e 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ny parameter of 
2a360 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
2a370 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f  any time.  The o
2a380 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a  nly guarantee.**
2a390 20 69 73 20 74 68 61 74 20 74 68 65 20 64 65 73   is that the des
2a3a0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
2a3b0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
2a3c0 65 20 6d 65 74 61 64 61 74 61 20 69 73 0a 2a 2a  e metadata is.**
2a3d0 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
2a3e0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
2a3f0 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 72  a-data is preser
2a400 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
2a410 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
2a420 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
2a430 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
2a440 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
2a450 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
2a460 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
2a470 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
2a480 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
2a490 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2a4a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2a4b0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2a4c0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
2a4d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2a4e0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2a4f0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2a500 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69  16272} The [sqli
2a510 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a520 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
2a530 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2a540 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
2a550 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2a560 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
2a570 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
2a580 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
2a590 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73  **          whos
2a5a0 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20  e context is C, 
2a5b0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65  or NULL if there
2a5c0 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   is no metadata 
2a5d0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
2a5e0 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74         with that
2a5f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2a600 2a 20 7b 46 31 36 32 37 34 7d 20 54 68 65 20 5b  * {F16274} The [
2a610 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a620 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e  ata(C,N,P,D)] in
2a630 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20  terface assigns 
2a640 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20  a metadata.**   
2a650 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50         pointer P
2a660 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61   to the Nth para
2a670 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
2a680 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63   function with c
2a690 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  ontext.**       
2a6a0 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36     C..**.** {F16
2a6b0 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  276} SQLite will
2a6c0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
2a6d0 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20  ructor D with a 
2a6e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a  single argument.
2a6f0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63  **          whic
2a700 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74  h is the metadat
2a710 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c  a pointer P foll
2a720 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a  owing a call to.
2a730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a740 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2a750 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20  (C,N,P,D)] when 
2a760 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
2a770 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20   hold.**        
2a780 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a    the metadata..
2a790 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53  **.** {F16277} S
2a7a0 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
2a7b0 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f  hold metadata fo
2a7c0 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  r an SQL functio
2a7d0 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  n parameter.**  
2a7e0 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65          when the
2a7f0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70   value of that p
2a800 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
2a810 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d  ..**.** {F16278}
2a820 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   When [sqlite3_s
2a830 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
2a840 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c  ,D)] is invoked,
2a850 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
2a860 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63  **          is c
2a870 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72  alled for any pr
2a880 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73  ior metadata ass
2a890 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2a8a0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
2a8b0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
2a8c0 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74  xt C and paramet
2a8d0 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  er N..**.** {F16
2a8e0 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  279} SQLite will
2a8f0 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72   call destructor
2a900 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61  s for any metada
2a910 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67  ta it is holding
2a920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
2a930 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72  a particular [pr
2a940 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a950 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a  ] S when either.
2a960 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a970 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f  ite3_reset(S)] o
2a980 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2a990 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
2a9a0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  d..*/.void *sqli
2a9b0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a9c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a9d0 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
2a9e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a9f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2aa00 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
2aa10 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
2aa20 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
2aa30 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
2aa40 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
2aa50 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
2aa60 61 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a  avior {F10280}.*
2aa70 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
2aa80 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72  pecial value for
2aa90 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2aaa0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
2aab0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
2aac0 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
2aad0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2aae0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2aaf0 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
2ab00 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2ab10 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2ab20 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2ab30 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2ab40 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2ab50 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2ab60 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2ab70 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2ab80 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2ab90 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45    The .** SQLITE
2aba0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
2abb0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2abc0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
2abd0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
2abe0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
2abf0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
2ac00 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
2ac10 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2ac20 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
2ac30 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
2ac40 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2ac50 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
2ac60 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
2ac70 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
2ac80 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
2ac90 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
2aca0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
2acb0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
2acc0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2acd0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
2ace0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
2acf0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
2ad00 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2ad10 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
2ad20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2ad30 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2ad40 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
2ad50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ad60 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
2ad70 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
2ad80 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d  unction {F16400}
2ad90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2ada0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
2adb0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
2adc0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
2add0 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
2ade0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
2adf0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
2ae00 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
2ae10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ae20 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ae30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ae40 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
2ae50 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2ae60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
2ae70 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
2ae80 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
2ae90 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
2aea0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2aeb0 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69  te3_bind_*] fami
2aec0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20  ly of functions 
2aed0 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20  used.** to bind 
2aee0 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
2aef0 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
2af00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2af10 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
2af20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
2af30 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2af40 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e  3_bind_* documen
2af50 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61  tation] for.** a
2af60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2af70 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2af80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2af90 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
2afa0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2afb0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
2afc0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2afd0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2afe0 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
2aff0 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
2b000 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
2b010 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
2b020 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
2b030 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
2b040 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
2b050 20 70 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20   parameter. .** 
2b060 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2b070 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
2b080 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
2b090 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2b0a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2b0b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2b0c0 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
2b0d0 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
2b0e0 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
2b0f0 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
2b100 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
2b110 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
2b120 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
2b130 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b140 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
2b150 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2b160 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2b170 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2b180 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2b190 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
2b1a0 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
2b1b0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
2b1c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2b1d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2b1e0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2b1f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b200 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
2b210 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
2b220 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
2b230 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
2b240 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
2b250 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
2b260 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
2b270 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
2b280 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2b290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b2a0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
2b2b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b2c0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
2b2d0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
2b2e0 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69  ssage.  SQLite i
2b2f0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
2b300 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
2b310 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2b320 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2b330 29 20 61 73 20 55 54 46 38 2e 20 53 51 4c 69 74  ) as UTF8. SQLit
2b340 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
2b350 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
2b360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b370 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 31  rror16() as UTF1
2b380 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
2b390 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74  yte order.  If t
2b3a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b3b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2b3c0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2b3d0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2b3e0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2b3f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2b400 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
2b410 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2b420 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
2b430 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2b440 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2b450 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20  ** If the third 
2b460 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2b470 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b480 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
2b490 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b4a0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
2b4b0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2b4c0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
2b4d0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
2b4e0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
2b4f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2b500 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
2b510 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  sage..** The sql
2b520 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b530 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
2b540 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2b550 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
2b560 65 20 61 20 63 6f 70 79 20 70 72 69 76 61 74 65  e a copy private
2b570 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
2b580 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2b590 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
2b5a0 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
2b5b0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2b5c0 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
2b5d0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
2b5e0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
2b5f0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
2b600 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20  ut harm..** The 
2b610 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b620 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
2b630 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
2b640 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
2b650 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
2b660 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
2b670 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
2b680 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66  unction.  By def
2b690 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
2b6a0 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
2b6b0 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73  E_ERROR.  A subs
2b6c0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
2b6d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b6e0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
2b6f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b700 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
2b710 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
2b720 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
2b730 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2b740 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
2b750 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2b760 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f  QLite.** to thro
2b770 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63  w an error indic
2b780 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
2b790 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
2b7a0 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70  o long.** to rep
2b7b0 72 65 73 65 6e 74 2e 20 20 54 68 65 20 73 71 6c  resent.  The sql
2b7c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
2b7d0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  m() interface.**
2b7e0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2b7f0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
2b800 74 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e 67 20  tion indicating 
2b810 74 68 61 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65  that the a.** me
2b820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2b830 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  failed..**.** Th
2b840 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b850 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
2b860 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2b870 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2b880 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b890 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2b8a0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
2b8b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2b8c0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
2b8d0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
2b8e0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
2b8f0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
2b900 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2b910 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2b920 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2b930 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b940 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2b950 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2b960 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
2b970 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
2b980 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2b990 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2b9a0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
2b9b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2b9c0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2b9d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b9e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b9f0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
2ba00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ba10 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
2ba20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ba30 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69  xt16(), .** sqli
2ba40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2ba50 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
2ba60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2ba70 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
2ba80 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
2ba90 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
2baa0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2bab0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2bac0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
2bad0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
2bae0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
2baf0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
2bb00 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
2bb10 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
2bb20 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
2bb30 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
2bb40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69  ctively..** SQLi
2bb50 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
2bb60 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
2bb70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
2bb80 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
2bb90 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
2bba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2bbb0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
2bbc0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
2bbd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2bbe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2bbf0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2bc00 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2bc10 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2bc20 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
2bc30 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2bc40 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ter .** through 
2bc50 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2bc60 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
2bc70 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2bc80 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2bc90 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2bca0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2bcb0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
2bcc0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
2bcd0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2bce0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
2bcf0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
2bd00 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2bd10 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
2bd20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2bd30 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
2bd40 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
2bd50 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2bd60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2bd70 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2bd80 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2bd90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2bda0 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
2bdb0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
2bdc0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
2bdd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
2bde0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
2bdf0 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f   the text or blo
2be00 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  b result when it
2be10 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
2be20 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2be30 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
2be40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2be50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2be60 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2be70 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2be80 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2be90 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2bea0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
2beb0 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  IC, then.** SQLi
2bec0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2bed0 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62  the text or blob
2bee0 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e 73 74   result is const
2bef0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a  ant space and.**
2bf00 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79 20 74   does not copy t
2bf10 68 65 20 73 70 61 63 65 20 6f 72 20 63 61 6c 6c  he space or call
2bf20 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68   a destructor wh
2bf30 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
2bf40 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2bf50 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
2bf60 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2bf70 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2bf80 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2bf90 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2bfa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2bfb0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
2bfc0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
2bfd0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
2bfe0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
2bff0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
2c000 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
2c010 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
2c020 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2c030 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
2c040 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
2c050 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2c060 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
2c070 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2c080 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2c090 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c0a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2c0b0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
2c0c0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2c0d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c0e0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
2c0f0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2c100 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ter.  The.** sql
2c110 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2c120 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
2c130 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2c140 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c150 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71  ].** so that [sq
2c160 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
2c170 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
2c180 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
2c190 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
2c1a0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
2c1b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2c1c0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
2c1d0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20  hout harm..** A 
2c1e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c1f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c200 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
2c210 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
2c220 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2c230 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c240 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
2c250 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
2c260 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
2c270 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
2c280 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
2c290 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
2c2a0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
2c2b0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2c2c0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
2c2d0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2c2e0 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e   .** than the on
2c2f0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2c300 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c310 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
2c320 61 74 20 72 65 63 69 65 76 65 64 0a 2a 2a 20 74  at recieved.** t
2c330 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2c340 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
2c350 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2c360 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2c370 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2c380 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20 64 65   {F16403} The de
2c390 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c  fault return val
2c3a0 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20  ue from any SQL 
2c3b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c  function is NULL
2c3c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d  ..**.** {F16406}
2c3d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2c3e0 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
2c3f0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
2c400 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2c410 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2c420 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2c430 20 74 6f 20 62 65 20 61 20 62 6c 6f 62 20 74 68   to be a blob th
2c440 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a  at is N bytes.**
2c450 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e            in len
2c460 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e  gth and with con
2c470 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20  tent pointed to 
2c480 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  by V..**.** {F16
2c490 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  409} The [sqlite
2c4a0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
2c4b0 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
2c4c0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2c4d0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2c4e0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2c4f0 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f   C to be the flo
2c500 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2c510 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
2c520 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2c530 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c  _result_error(C,
2c540 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  V,N)] interface 
2c550 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
2c560 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
2c570 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2c580 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
2c590 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
2c5a0 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
2c5b0 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
2c5c0 20 61 6e 64 20 61 20 55 54 46 38 20 65 72 72 6f   and a UTF8 erro
2c5d0 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64  r message copied
2c5e0 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
2c5f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
2c600 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72  rst zero byte or
2c610 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61   until N bytes a
2c620 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20  re read if N is 
2c630 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  positive..**.** 
2c640 7b 46 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71  {F16415} The [sq
2c650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c660 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74  or16(C,V,N)] int
2c670 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2c680 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
2c690 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66        value of f
2c6a0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2c6b0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
2c6c0 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
2c6d0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2c6e0 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54  _ERROR] and a UT
2c6f0 46 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  F16 native byte 
2c700 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73  order error mess
2c710 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  age.**          
2c720 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70  copied from V up
2c730 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2c740 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72  ro terminator or
2c750 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a   until N bytes.*
2c760 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72  *          are r
2c770 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
2c780 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  tive..**.** {F16
2c790 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  418} The [sqlite
2c7a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2c7b0 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66  oobig(C)] interf
2c7c0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
2c7d0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
2c7e0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
2c7f0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2c800 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
2c810 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
2c820 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2c830 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e  E_TOOBIG] and an
2c840 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
2c850 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
2c860 2a 20 7b 46 31 36 34 32 31 7d 20 54 68 65 20 5b  * {F16421} The [
2c870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2c880 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69  rror_nomem(C)] i
2c890 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2c8a0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
2c8b0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
2c8c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
2c8d0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
2c8e0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
2c8f0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
2c900 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e  SQLITE_NOMEM] an
2c910 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
2c920 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2c930 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54  **.** {F16424} T
2c940 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c950 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c  lt_error_code(C,
2c960 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  E)] interface ch
2c970 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
2c980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
2c990 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
2c9a0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2c9b0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2c9c0 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20  or code E..**   
2c9d0 20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72         The error
2c9e0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73   message text is
2c9f0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
2ca00 2a 20 7b 46 31 36 34 32 37 7d 20 54 68 65 20 5b  * {F16427} The [
2ca10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2ca20 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  nt(C,V)] interfa
2ca30 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2ca40 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2ca50 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2ca60 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2ca70 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76  32-bit integer v
2ca80 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
2ca90 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  16430} The [sqli
2caa0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2cab0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
2cac0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2cad0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2cae0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2caf0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34  n C to be the 64
2cb00 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c  -bit integer val
2cb10 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ue V..**.** {F16
2cb20 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  433} The [sqlite
2cb30 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29  3_result_null(C)
2cb40 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2cb50 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2cb60 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2cb70 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2cb80 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
2cb90 20 7b 46 31 36 34 33 36 7d 20 54 68 65 20 5b 73   {F16436} The [s
2cba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2cbb0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  xt(C,V,N,D)] int
2cbc0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2cbd0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
2cbe0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
2cbf0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2cc00 74 68 65 20 55 54 46 38 20 73 74 72 69 6e 67 0a  the UTF8 string.
2cc10 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 70  **          V up
2cc20 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2cc30 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
2cc40 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
2cc50 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
2cc60 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
2cc70 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
2cc80 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54  **.** {F16439} T
2cc90 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2cca0 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
2ccb0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
2ccc0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2ccd0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2cce0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2ccf0 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36   to be the UTF16
2cd00 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2cd10 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
2cd20 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
2cd30 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
2cd40 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  N is.**         
2cd50 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65   negative or the
2cd60 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
2cd70 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
2cd80 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
2cd90 7b 46 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71  {F16442} The [sq
2cda0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cdb0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16be(C,V,N,D)] 
2cdc0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2cdd0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2cde0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2cdf0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2ce00 62 65 20 74 68 65 20 55 54 46 31 36 20 62 69 67  be the UTF16 big
2ce10 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
2ce20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
2ce30 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2ce40 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20  o if N is.**    
2ce50 20 20 20 20 20 20 69 73 20 6e 65 67 61 74 69 76        is negativ
2ce60 65 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e  e or the first N
2ce70 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e   bytes or V if N
2ce80 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2ce90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 7d  ..**.** {F16445}
2cea0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2ceb0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
2cec0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
2ced0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2cee0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cef0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2cf00 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
2cf10 54 46 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  TF16 little-endi
2cf20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2cf30 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
2cf40 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
2cf50 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  N is.**         
2cf60 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65   negative or the
2cf70 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
2cf80 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
2cf90 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
2cfa0 7b 46 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71  {F16448} The [sq
2cfb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2cfc0 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  ue(C,V)] interfa
2cfd0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2cfe0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2cff0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2d000 69 6f 6e 20 43 20 74 6f 20 62 65 20 5b 75 6e 70  ion C to be [unp
2d010 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d020 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20  _value].**      
2d030 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a      object V..**
2d040 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54 68 65  .** {F16451} The
2d050 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d060 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20  _zeroblob(C,N)] 
2d070 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2d080 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d090 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2d0a0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2d0b0 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 62 6c 6f  be an N-byte blo
2d0c0 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a  b of all zeros..
2d0d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 54  **.** {F16454} T
2d0e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2d0f0 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20  lt_error()] and 
2d100 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d110 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20  error16()].**   
2d120 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2d130 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  s make a copy of
2d140 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73   their error mes
2d150 73 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66  sage strings bef
2d160 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
2d170 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
2d180 20 7b 46 31 36 34 35 37 7d 20 49 66 20 74 68 65   {F16457} If the
2d190 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
2d1a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2d1b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2d1c0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
2d1d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2d1e0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
2d1f0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
2d200 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
2d210 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
2d220 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2d230 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
2d240 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
2d250 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d260 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2d270 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
2d280 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49  e constant [SQLI
2d290 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20  TE_STATIC].**   
2d2a0 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64         then no d
2d2b0 65 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65  estructor is eve
2d2c0 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  r called on the 
2d2d0 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51  pointer V and SQ
2d2e0 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  Lite.**         
2d2f0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20   assumes that V 
2d300 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a  is immutable..**
2d310 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49 66 20  .** {F16460} If 
2d320 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
2d330 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2d340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2d350 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
2d360 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d370 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
2d380 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
2d390 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d3a0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
2d3b0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d3c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2d3d0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
2d3e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d3f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d400 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
2d410 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a   the constant.**
2d420 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2d430 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
2d440 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  n the interfaces
2d450 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2d460 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d470 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e   content of V an
2d480 64 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f  d retains the co
2d490 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36  py..**.** {F1646
2d4a0 33 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74  3} If the D dest
2d4b0 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72  ructor parameter
2d4c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2d4d0 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
2d4e0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2d4f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d500 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  text(C,V,N,D)], 
2d510 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d520 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
2d530 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
2d540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d550 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16be(C,V,N,D)]
2d560 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
2d570 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d580 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
2d590 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75  D)] is some valu
2d5a0 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
2d5b0 20 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e           the con
2d5c0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53  stants [SQLITE_S
2d5d0 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49  TATIC] and [SQLI
2d5e0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68  TE_TRANSIENT] th
2d5f0 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  en .**          
2d600 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2d610 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2d620 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74  r D with V as it
2d630 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a  s only argument.
2d640 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
2d650 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2d660 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75   with the V valu
2d670 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
2d680 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
2d690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d6a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d6b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2d6c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2d6d0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
2d6e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d6f0 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
2d700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d710 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
2d720 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2d730 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2d740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d750 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
2d760 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2d770 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
2d780 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d790 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
2d7a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2d7b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d7c0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
2d7d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2d7e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d7f0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2d800 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d810 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2d820 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2d830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d840 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2d850 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
2d860 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
2d870 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
2d880 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
2d890 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
2d8a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2d8b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d8c0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
2d8d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d8e0 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
2d8f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2d900 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d910 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
2d920 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d930 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2d940 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2d950 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d960 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
2d970 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2d980 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2d990 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2d9a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d9b0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
2d9c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d9d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
2d9e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2d9f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2da00 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
2da10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2da20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
2da30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2da40 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2da50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2da60 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2da70 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
2da80 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
2da90 63 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a  ces {F16600}.**.
2daa0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2dab0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
2dac0 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
2dad0 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
2dae0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20  e.** [sqlite3*] 
2daf0 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64  handle specified
2db00 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2db10 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54  gument. .**.** T
2db20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
2db30 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
2db40 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
2db50 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
2db60 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
2db70 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2db80 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
2db90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2dba0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
2dbb0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2dbc0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2dbd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2dbe0 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a  . In all cases.*
2dbf0 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
2dc00 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
2dc10 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2dc20 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2dc30 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
2dc40 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  ay be one of the
2dc50 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49   constants [SQLI
2dc60 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
2dc70 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72  LITE_UTF16LE] or
2dc80 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2dc90 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2dca0 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
2dcb0 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
2dcc0 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
2dcd0 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
2dce0 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
2dcf0 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
2dd00 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
2dd10 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20  ndian or UTF-16 
2dd20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  big-endian respe
2dd30 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20  ctively. The.** 
2dd40 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
2dd50 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51  ight also be [SQ
2dd60 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2dd70 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ED] to indicate 
2dd80 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74  that.** the rout
2dd90 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e  ine expects poin
2dda0 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77  ters to 16-bit w
2ddb0 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69  ord aligned stri
2ddc0 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20  ngs.** of UTF16 
2ddd0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
2dde0 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te order of the 
2ddf0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
2de00 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
2de10 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
2de20 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
2de30 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2de40 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
2de50 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e  ent.  If it is N
2de60 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
2de70 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
2de80 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
2de90 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
2dea0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
2deb0 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
2dec0 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d  re)..** Each tim
2ded0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
2dee0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75  n.** supplied fu
2def0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
2df00 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20  d, it is passed 
2df10 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
2df20 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  id* passed as.**
2df30 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2df40 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2df50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2df60 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2df70 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2df80 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72  n16() as its fir
2df90 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
2dfa0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
2dfb0 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
2dfc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  he application-s
2dfd0 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
2dfe0 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c  are two strings,
2dff0 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65  .** each represe
2e000 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74  nted by a (lengt
2e010 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e  h, data) pair an
2e020 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65  d encoded in the
2e030 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61   encoding.** tha
2e040 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20  t was passed as 
2e050 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2e060 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  nt when the coll
2e070 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77  ation sequence w
2e080 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  as.** registered
2e090 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c  . {END} The appl
2e0a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2e0b0 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
2e0c0 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
2e0d0 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
2e0e0 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
2e0f0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 73 74  .** the first st
2e100 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
2e110 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
2e120 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
2e130 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e   second.** strin
2e140 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31  g. i.e. (STRING1
2e150 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a   - STRING2)..**.
2e160 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
2e170 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2e180 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
2e190 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e1a0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78  ollation().** ex
2e1b0 63 61 70 74 20 74 68 61 74 20 69 74 20 74 61 6b  capt that it tak
2e1c0 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75  es an extra argu
2e1d0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2e1e0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a  destructor for.*
2e1f0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e  * the collation.
2e200 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72    The destructor
2e210 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   is called when 
2e220 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
2e230 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e  .** destroyed an
2e240 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  d is passed a co
2e250 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  py of the fourth
2e260 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a   parameter void*
2e270 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74   pointer.** of t
2e280 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
2e290 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2e2a0 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20  ..** Collations 
2e2b0 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68  are destroyed wh
2e2c0 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f  en.** they are o
2e2d0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
2e2e0 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  er calls to the 
2e2f0 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
2e300 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  on functions.** 
2e310 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c  or when the [sql
2e320 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20  ite3*] database 
2e330 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64  handle is closed
2e340 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2e350 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
2e360 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2e370 2a 20 7b 46 31 36 36 30 33 7d 20 41 20 73 75 63  * {F16603} A suc
2e380 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2e390 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2e3a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e3b0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
2e3c0 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72  ,E,P,F,D)] inter
2e3d0 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  face.**         
2e3e0 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74   registers funct
2e3f0 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d  ion F as the com
2e400 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
2e410 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20   used to.**     
2e420 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63       implement c
2e430 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 5b 64  ollation X on [d
2e440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e450 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20  on] B for.**    
2e460 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20        databases 
2e470 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  having encoding 
2e480 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34  E..**.** {F16604
2e490 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74  } SQLite underst
2e4a0 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d  ands the X param
2e4b0 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
2e4c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
2e4d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e4e0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
2e4f0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
2e500 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2e510 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20  UTF-8 string in 
2e520 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67  which case is ig
2e530 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20  nored for ASCII 
2e540 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a  characters and.*
2e550 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69  *          is si
2e560 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f  gnificant for no
2e570 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65  n-ASCII characte
2e580 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  rs..**.** {F1660
2e590 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61  6} Successive ca
2e5a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2e5b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e5c0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
2e5d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
2e5e0 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
2e5f0 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
2e600 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
2e610 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  or values.**    
2e620 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61        of P, F, a
2e630 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nd D..**.** {F16
2e640 36 30 39 7d 20 54 68 65 20 64 65 73 74 72 75 63  609} The destruc
2e650 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65  tor D in [sqlite
2e660 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e670 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2e680 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
2e690 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
2e6a0 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69   it is called wi
2e6b0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
2e6c0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
2e6d0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e     collating fun
2e6e0 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
2e6f0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
2e700 2a 20 7b 46 31 36 36 31 32 7d 20 41 20 63 6f 6c  * {F16612} A col
2e710 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2e720 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
2e730 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64  it is overloaded
2e740 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d  ..**.** {F16615}
2e750 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
2e760 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
2e770 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2e780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
2e790 20 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f            is clo
2e7a0 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
2e7b0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
2e7c0 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54 68 65 20  ** {F16618} The 
2e7d0 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71  pointer P in [sq
2e7e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e7f0 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
2e800 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
2e810 20 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68      is passed th
2e820 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
2e830 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2e840 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a  the comparison.*
2e850 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
2e860 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75  ion F for all su
2e870 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2e880 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a  ions of F..**.**
2e890 20 7b 46 31 36 36 32 31 7d 20 41 20 63 61 6c 6c   {F16621} A call
2e8a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2e8b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
2e8c0 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61  X,E,P,F)] is exa
2e8d0 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctly.**         
2e8e0 20 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63   the same as a c
2e8f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e900 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e910 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20  _v2()] with.**  
2e920 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
2e930 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
2e940 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f  a NULL destructo
2e950 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34  r..**.** {F16624
2e960 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73  } Following a [s
2e970 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e980 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
2e990 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,P,F,D)],.**    
2e9a0 20 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65        SQLite use
2e9b0 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  s the comparison
2e9c0 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20   function F for 
2e9d0 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69  all text compari
2e9e0 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
2e9f0 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 5b 64  operations on [d
2ea00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ea10 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61  on] B on text va
2ea20 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20  lues that.**    
2ea30 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f        use the co
2ea40 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
2ea50 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b   name X..**.** {
2ea60 46 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c  F16627} The [sql
2ea70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ea80 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c  ation16(B,X,E,P,
2ea90 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61  F)] works the sa
2eaa0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  me.**          a
2eab0 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  s [sqlite3_creat
2eac0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c  e_collation(B,X,
2ead0 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74  E,P,F)] except t
2eae0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hat the.**      
2eaf0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61      collation na
2eb00 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f  me X is understo
2eb10 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  od as UTF-16 in 
2eb20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2eb30 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
2eb40 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a  stead of UTF-8..
2eb50 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57  **.** {F16630} W
2eb60 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d  hen multiple com
2eb70 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
2eb80 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
2eb90 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  for the same.** 
2eba0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
2ebb0 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c  ng sequence, SQL
2ebc0 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20  ite chooses the 
2ebd0 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65  one whose text e
2ebe0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ncoding.**      
2ebf0 20 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65      requires the
2ec00 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2ec10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2ec20 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
2ec30 20 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e           text en
2ec40 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61  coding of the da
2ec50 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73  tabase..*/.int s
2ec60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2ec70 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
2ec80 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2ec90 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2eca0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2ecb0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2ecc0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2ecd0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2ece0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2ecf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2ed00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2ed10 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2ed20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2ed30 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2ed40 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
2ed50 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2ed60 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2ed70 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2ed80 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
2ed90 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
2eda0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2edb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2edc0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
2edd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ede0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2edf0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2ee00 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2ee10 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2ee20 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2ee30 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
2ee40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2ee50 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
2ee60 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d  llbacks {F16700}
2ee70 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
2ee80 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
2ee90 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
2eea0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
2eeb0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
2eec0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
2eed0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
2eee0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
2eef0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
2ef00 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68  he.** database h
2ef10 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c  andle to be call
2ef20 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
2ef30 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2ef40 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a  on sequence is.*
2ef50 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  * required..**.*
2ef60 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * If the functio
2ef70 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
2ef80 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2ef90 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2efa0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
2efb0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
2efc0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
2efd0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
2efe0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
2eff0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
2f000 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36 37 30  in UTF-8. {F1670
2f010 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  3} If sqlite3_co
2f020 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2f030 28 29 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  () is used, the 
2f040 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73  names.** are pas
2f050 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
2f060 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
2f070 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61  byte order. A ca
2f080 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ll to either.** 
2f090 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
2f0a0 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
2f0b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57  allback..**.** W
2f0c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
2f0d0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
2f0e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2f0f0 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
2f100 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
2f110 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
2f120 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2f130 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
2f140 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f150 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
2f160 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2f170 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
2f180 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 54 68  e.** handle.  Th
2f190 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2f1a0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2f1b0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
2f1c0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2f1d0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2f1e0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
2f1f0 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72  he most.** desir
2f200 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
2f210 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2f220 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
2f230 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f  uired..** The fo
2f240 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2f250 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2f260 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
2f270 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2f280 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
2f290 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
2f2a0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
2f2b0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
2f2c0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
2f2d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2f2e0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
2f2f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2f300 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
2f310 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f320 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
2f330 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2f340 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30  TS:.**.** {F1670
2f350 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
2f360 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2f370 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f380 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20  d(D,P,F)].**    
2f390 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2f3a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f3b0 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75  ed16(D,P,F)] cau
2f3c0 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ses.**          
2f3d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2f3e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69  nnection] D to i
2f3f0 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46  nvoke callback F
2f400 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20   with first.**  
2f410 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
2f420 72 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20  r P whenever it 
2f430 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73  needs a comparis
2f440 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  on function for 
2f450 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  a.**          co
2f460 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
2f470 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
2f480 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a  t know about..**
2f490 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45 61 63  .** {F16704} Eac
2f4a0 68 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  h successful cal
2f4b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2f4c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2f4d0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2f4e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2f4f0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20  ion_needed16()] 
2f500 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61  overrides the ca
2f510 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65  llback registere
2f520 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  d.**          on
2f530 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2f540 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f550 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  by prior calls t
2f560 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  o either.**     
2f570 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a       interface..
2f580 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d 20 54  **.** {F16706} T
2f590 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72  he name of the r
2f5a0 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69  equested collati
2f5b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73  ng function pass
2f5c0 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ed in the.**    
2f5d0 20 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65        4th parame
2f5e0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2f5f0 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20  ack is in UTF-8 
2f600 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  if the callback.
2f610 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20  **          was 
2f620 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2f630 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2f640 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
2f650 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
2f660 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76   in UTF-16 nativ
2f670 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
2f680 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
2f690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
2f6a0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
2f6b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f6c0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a  _needed16()]..**
2f6d0 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  .** .*/.int sqli
2f6e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f6f0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
2f700 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
2f710 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2f720 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2f730 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
2f740 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f750 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2f760 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2f770 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
2f780 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2f790 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2f7a0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2f7b0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2f7c0 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
2f7d0 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
2f7e0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
2f7f0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
2f800 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
2f810 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
2f820 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2f830 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2f840 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2f850 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2f860 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2f870 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2f880 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
2f890 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2f8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f8b0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2f8c0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2f8d0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2f8e0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2f8f0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
2f900 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
2f910 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
2f920 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
2f930 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
2f940 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
2f950 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
2f960 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
2f970 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
2f980 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
2f990 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
2f9a0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
2f9b0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2f9c0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2f9d0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2f9e0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2f9f0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2fa00 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2fa10 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
2fa20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2fa30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2fa40 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
2fa50 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
2fa60 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
2fa70 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
2fa80 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
2fa90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
2faa0 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
2fab0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
2fac0 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a  me {F10530}.**.*
2fad0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
2fae0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  eep() function.*
2faf0 2a 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  * causes the cur
2fb00 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
2fb10 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2fb20 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
2fb30 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
2fb40 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
2fb50 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
2fb60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
2fb70 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2fb80 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
2fb90 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
2fba0 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c  sts with .** mil
2fbb0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
2fbc0 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
2fbd0 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
2fbe0 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a  rounded up to .*
2fbf0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
2fc00 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
2fc10 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
2fc20 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
2fc30 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ly .** requested
2fc40 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
2fc50 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
2fc60 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51  turned..**.** SQ
2fc70 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
2fc80 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
2fc90 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
2fca0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
2fcb0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
2fcc0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
2fcd0 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ject..**.** INVA
2fce0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2fcf0 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  10533} The [sqli
2fd00 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e  te3_sleep(M)] in
2fd10 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20  terface invokes 
2fd20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20  the xSleep.**   
2fd30 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66         method of
2fd40 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
2fd50 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69  lite3_vfs|VFS] i
2fd60 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20  n order to.**   
2fd70 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65         suspend e
2fd80 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
2fd90 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66  current thread f
2fda0 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20  or at least.**  
2fdb0 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73          M millis
2fdc0 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  econds..**.** {F
2fdd0 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  10536} The [sqli
2fde0 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e  te3_sleep(M)] in
2fdf0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2fe00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2fe10 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73            millis
2fe20 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
2fe30 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74  actually request
2fe40 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74  ed of the operat
2fe50 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2fe60 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69  system, which mi
2fe70 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
2fe80 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  an the parameter
2fe90 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   M..*/.int sqlit
2fea0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
2feb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fec0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
2fed0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
2fee0 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30  orary Files {F10
2fef0 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  310}.**.** If th
2ff00 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
2ff10 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
2ff20 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
2ff30 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
2ff40 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
2ff50 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72   (a.ka. director
2ff60 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
2ff70 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
2ff80 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
2ff90 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
2ffa0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
2ffb0 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
2ffc0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c  iable.** is NULL
2ffd0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
2ffe0 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61  QLite does a sea
2fff0 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
30000 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79  priate temporary
30010 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f  .** file directo
30020 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
30030 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69  not safe to modi
30040 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
30050 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65   once a database
30060 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68   connection.** h
30070 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
30080 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
30090 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
300a0 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
300b0 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
300c0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
300d0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
300e0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
300f0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
30100 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
30110 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
30120 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
30130 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
30140 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
30150 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
30160 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30170 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
30180 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20  The Database Is 
30190 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  In Auto-Commit M
301a0 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a  ode {F12930}.**.
301b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
301c0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
301d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
301e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
301f0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
30200 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
30210 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
30220 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
30230 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
30240 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f  ectively.   Auto
30250 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
30260 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e  n.** by default.
30270 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
30280 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
30290 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
302a0 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ment..** Autocom
302b0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 65 6e  mit mode is reen
302c0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
302d0 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
302e0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
302f0 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
30300 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
30310 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
30320 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
30330 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
30340 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  s (errors includ
30350 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
30360 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
30370 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  ], .** [SQLITE_N
30380 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
30390 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
303a0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
303b0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
303c0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
303d0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
303e0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
303f0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
30400 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65  nd out if SQLite
30410 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
30420 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
30430 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
30440 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
30450 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
30460 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
30470 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
30480 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69  12931} The [sqli
30490 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
304a0 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  it(D)] interface
304b0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
304c0 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  o or.**         
304d0 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61   zero if the [da
304e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
304f0 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f  n] D is or is no
30500 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  t in autocommit.
30510 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65  **          mode
30520 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
30530 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41  **.** {F12932} A
30540 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
30550 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
30560 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20  .**.** {F12933} 
30570 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
30580 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
30590 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47   successful [BEG
305a0 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
305b0 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75  *.** {F12934} Au
305c0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
305d0 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75   enabled by a su
305e0 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54  ccessful [COMMIT
305f0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a  ] or [ROLLBACK].
30600 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74  **          stat
30610 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a  ement..** .**.**
30620 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
30630 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 66  *.** {U12936} If
30640 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
30650 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
30660 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
30670 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
30680 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63            connec
30690 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
306a0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
306b0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
306c0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  urn value.**    
306d0 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e        is undefin
306e0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
306f0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
30700 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
30710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46  .** CAPI3REF:  F
30720 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
30730 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
30740 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30750 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13120}.**.** T
30760 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
30770 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  ndle interface.*
30780 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73  * returns the [s
30790 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
307a0 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63  e handle to whic
307b0 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  h a.** [prepared
307c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
307d0 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64 61 74 61  ngs..** The data
307e0 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75  base handle retu
307f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
30800 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  db_handle.** is 
30810 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
30820 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
30830 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61  s.** the first a
30840 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
30850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30860 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
30870 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61  iants.** that wa
30880 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
30890 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
308a0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
308b0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
308c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
308d0 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
308e0 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69  _db_handle(S)] i
308f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30900 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
30910 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64         to the [d
30920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30930 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
30940 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
30950 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30960 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74  ent] S..*/.sqlit
30970 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
30980 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
30990 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  mt*);.../*.** CA
309a0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
309b0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
309c0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
309d0 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a  ks {F12950}.**.*
309e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
309f0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
30a00 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
30a10 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
30a20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
30a30 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
30a40 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
30a50 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
30a60 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
30a70 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
30a80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
30a90 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
30aa0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30ac0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
30ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
30ae0 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
30af0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
30b00 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
30b10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
30b20 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
30b30 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
30b40 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
30b50 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
30b60 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
30b70 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
30b80 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
30b90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30bb0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
30bc0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
30bd0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
30be0 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ugh.** to the ca
30bf0 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20  llback.  If the 
30c00 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
30c10 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
30c20 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  on .** returns n
30c30 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
30c40 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
30c50 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
30c60 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  lback..**.** If 
30c70 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
30c80 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
30c90 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a  registered, its.
30ca0 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ** pArg value is
30cb0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
30cc0 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
30cd0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
30ce0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
30cf0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
30d00 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
30d10 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
30d20 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
30d30 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
30d40 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
30d50 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c  ve been .** roll
30d60 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
30d70 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
30d80 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
30d90 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
30da0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
30db0 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
30dc0 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
30dd0 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54  k to occur..** T
30de0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
30df0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
30e00 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
30e10 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
30e20 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e30 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
30e40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30e50 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
30e60 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
30e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
30e80 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
30e90 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72  nsaction is.** r
30ea0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
30eb0 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c  se a commit call
30ec0 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f  back returned no
30ed0 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f  n-zero..** <todo
30ee0 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20  > Check on this 
30ef0 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68  </todo>.**.** Th
30f00 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65  ese are experime
30f10 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
30f20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20  and are subject 
30f30 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a  to change..**.**
30f40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
30f50 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20  ** {F12951} The 
30f60 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
30f70 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
30f80 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
30f90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30fa0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
30fb0 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
30fc0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
30fd0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
30fe0 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
30ff0 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e  ction commits on
31000 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31010 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
31020 7b 46 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71  {F12952} The [sq
31030 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
31040 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
31050 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
31060 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
31070 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
31080 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
31090 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  th the same .** 
310a0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
310b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20  se connection ] 
310c0 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74  D , or NULL on t
310d0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
310e0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
310f0 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61  particular [data
31100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31110 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35   D..**.** {F1295
31120 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
31130 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
31140 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
31150 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
31160 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
31170 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
31180 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
31190 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 20 61  2954} If the F a
311a0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
311b0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
311c0 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a  D,F,P)] is NULL.
311d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
311e0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
311f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
31200 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  celled and no ca
31210 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
31220 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
31230 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
31240 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20   commits..**.** 
31250 7b 46 31 32 39 35 35 7d 20 49 66 20 74 68 65 20  {F12955} If the 
31260 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
31270 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
31280 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
31290 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
312a0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
312b0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
312c0 20 7b 46 31 32 39 36 31 7d 20 54 68 65 20 5b 73   {F12961} The [s
312d0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
312e0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
312f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
31300 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31310 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
31320 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
31330 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
31340 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
31350 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
31360 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
31370 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
31380 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
31390 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20  ** {F12962} The 
313a0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
313b0 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
313c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
313d0 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20   the P.**       
313e0 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d     argument from
313f0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
31400 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ll with the same
31410 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64   .**          [d
31420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31430 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c  on ] D , or NULL
31440 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61   on the first ca
31450 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ll.**          f
31460 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
31470 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31480 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
31490 46 31 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c  F12963} Each cal
314a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  l to [sqlite3_ro
314b0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f  llback_hook()] o
314c0 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61  verwrites the ca
314d0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
314e0 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79     registered by
314f0 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a   prior calls..**
31500 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49 66 20  .** {F12964} If 
31510 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74  the F argument t
31520 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  o [sqlite3_rollb
31530 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
31540 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20   is NULL.**     
31550 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f       then the ro
31560 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c  llback hook call
31570 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65  back is cancelle
31580 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63  d and no callbac
31590 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
315a0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
315b0 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
315c0 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  s back..*/.void 
315d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
315e0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
315f0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
31600 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
31610 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
31620 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
31630 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
31640 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
31650 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
31660 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
31670 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 37 30  allbacks {F12970
31680 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
31690 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
316a0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
316b0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
316c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ack function wit
316d0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
316e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69  onnection identi
316f0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
31700 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
31710 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
31720 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
31730 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
31740 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
31750 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
31760 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
31770 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
31780 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d  tion for the sam
31790 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  e .** database c
317a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
317b0 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rridden..**.** T
317c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
317d0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
317e0 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
317f0 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
31800 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61   .** row is upda
31810 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
31820 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 54 68   deleted. .** Th
31830 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31840 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
31850 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66   is.** a copy of
31860 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
31870 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  ent to sqlite3_u
31880 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
31890 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c   The second call
318a0 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  back .** argumen
318b0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
318c0 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
318d0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20  LITE_DELETE] or 
318e0 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
318f0 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
31900 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
31910 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
31920 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e  allback to be in
31930 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68  voked..** The th
31940 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72  ird and .** four
31950 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
31960 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
31970 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
31980 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
31990 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65  d .** table name
319a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
319b0 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
319c0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
319d0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
319e0 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f   .** the rowid o
319f0 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e  f the row..** In
31a00 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
31a10 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
31a20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20  the rowid after 
31a30 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20 74  .** the update t
31a40 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
31a50 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
31a60 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
31a70 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
31a80 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
31a90 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
31aa0 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
31ab0 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
31ac0 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ence)..**.** If 
31ad0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
31ae0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
31af0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20  registered, its 
31b00 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73  pArg value.** is
31b10 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
31b20 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
31b30 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  turned..**.** IN
31b40 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
31b50 7b 46 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71  {F12971} The [sq
31b60 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
31b70 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
31b80 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62  ace causes callb
31b90 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
31ba0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
31bb0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69   invoked with fi
31bc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20  rst parameter P 
31bd0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
31be0 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77       a table row
31bf0 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e   is modified, in
31c00 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74  serted, or delet
31c10 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ed on.**        
31c20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
31c30 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
31c40 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20 5b 73   {F12973} The [s
31c50 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31c60 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
31c70 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
31c80 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
31c90 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20     of P for the 
31ca0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e  previous call on
31cb0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
31cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31cd0 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  D,.**          o
31ce0 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66  r NULL for the f
31cf0 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  irst call..**.**
31d00 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74 68 65   {F12975} If the
31d10 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c   update hook cal
31d20 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69  lback F in [sqli
31d30 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
31d40 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20  D,F,P)].**      
31d50 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e      is NULL then
31d60 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63   the no update c
31d70 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64  allbacks are mad
31d80 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37  e..**.** {F12977
31d90 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
31da0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
31db0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72  ook(D,F,P)] over
31dc0 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c  rides prior call
31dd0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
31de0 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66   the same interf
31df0 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ace on the same 
31e00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31e10 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
31e20 46 31 32 39 37 39 7d 20 54 68 65 20 75 70 64 61  F12979} The upda
31e30 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
31e40 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
31e50 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
31e60 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  stem.**         
31e70 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73 20   tables such as 
31e80 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
31e90 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
31ea0 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a  e are modified..
31eb0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54  **.** {F12981} T
31ec0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
31ed0 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61 74  ter to the updat
31ee0 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20  e callback .**  
31ef0 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f          is one o
31f00 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
31f10 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
31f20 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  E] or [SQLITE_UP
31f30 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DATE],.**       
31f40 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20     depending on 
31f50 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
31f60 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
31f70 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76  llback to be inv
31f80 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
31f90 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20 61  983} The third a
31fa0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
31fb0 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
31fc0 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
31fd0 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
31fe0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
31ff0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
32000 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65 20  s which are the 
32010 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
32020 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
32030 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74  e and table that
32040 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 65   is being update
32050 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20  d...** {F12985} 
32060 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
32070 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
32080 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
32090 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20   row after.**   
320a0 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e 67         the chang
320b0 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69  e occurs..*/.voi
320c0 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
320d0 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
320e0 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
320f0 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
32100 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
32110 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
32120 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
32130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32140 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
32150 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
32160 20 43 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a   Cache {F10330}.
32170 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
32180 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
32190 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
321a0 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
321b0 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
321c0 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
321d0 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 63  ctures between c
321e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68  onnections to th
321f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
32200 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65  .** Sharing is e
32210 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
32220 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61  gument is true a
32230 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
32240 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  he argument.** i
32250 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43  s false..**.** C
32260 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
32270 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
32280 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65  bled.** for an e
32290 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b  ntire process. {
322a0 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61 20 63  END} This is a c
322b0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
322c0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
322d0 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76 65  ..** In prior ve
322e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
322f0 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a  , sharing was.**
32300 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
32310 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
32320 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
32330 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
32340 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
32350 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
32360 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
32370 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
32380 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
32390 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
323a0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
323b0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
323c0 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
323d0 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
323e0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
323f0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
32400 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
32410 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
32420 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
32430 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
32440 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
32450 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
32460 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
32470 2e 20 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a  .   When shared.
32480 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
32490 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
324a0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
324b0 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  )] API used to r
324c0 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
324d0 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
324e0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
324f0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  error..**.** Thi
32500 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
32510 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
32520 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
32530 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20  s.** enabled or 
32540 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73  disabled success
32550 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
32560 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65  r code].** is re
32570 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
32580 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63  ..**.** Shared c
32590 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
325a0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
325b0 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
325c0 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
325d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
325e0 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
325f0 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
32600 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
32610 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
32620 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
32630 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ly..**.** INVARI
32640 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  ANTS:.** .** {F1
32650 30 33 33 31 7d 20 41 20 73 75 63 63 65 73 73 66  0331} A successf
32660 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
32670 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
32680 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29  _shared_cache(B)
32690 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
326a0 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  ll enable or dis
326b0 61 62 6c 65 20 73 68 61 72 65 64 20 63 61 63 68  able shared cach
326c0 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73  e mode for any s
326d0 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20  ubsequently.**  
326e0 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64 20          created 
326f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32700 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d  tion] in the sam
32710 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  e process..**.**
32720 20 7b 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73   {F10336} When s
32730 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 65  hared cache is e
32740 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
32750 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
32760 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  le()].**        
32770 20 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c    interface will
32780 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
32790 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  n error..**.** {
327a0 46 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c  F10337} The [sql
327b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
327c0 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74  ed_cache(B)] int
327d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
327e0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
327f0 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
32800 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c   cache was enabl
32810 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73  ed or disabled s
32820 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a  uccessfully..**.
32830 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72  ** {F10339} Shar
32840 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
32850 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
32860 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32870 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
32880 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
32890 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65   CAPI3REF:  Atte
328a0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
328b0 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d   Memory {F17340}
328c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
328d0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
328e0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  y() interface at
328f0 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65  tempts to.** fre
32900 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61  e N bytes of hea
32910 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
32920 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
32930 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a  ential memory.**
32940 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c   allocations hel
32950 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
32960 65 20 6c 61 62 72 61 72 79 2e 20 7b 45 4e 44 7d  e labrary. {END}
32970 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a    Memory used.**
32980 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
32990 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  se pages to impr
329a0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
329b0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
329c0 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  .** non-essentia
329d0 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71 6c 69 74  l memory.  Sqlit
329e0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
329f0 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  y() returns.** t
32a00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32a10 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
32a20 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  d, which might b
32a30 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a  e more or less.*
32a40 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  * than the amoun
32a50 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a  t requested..**.
32a60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
32a70 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54 68  *.** {F17341} Th
32a80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  e [sqlite3_relea
32a90 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e  se_memory(N)] in
32aa0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
32ab0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
32ac0 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20  free N bytes of 
32ad0 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
32ae0 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
32af0 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20  essential.**    
32b00 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c        memory all
32b10 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79  ocations held by
32b20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 61   the database la
32b30 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  brary..**.** {F1
32b40 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6342} The [sqlit
32b50 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
32b60 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68  y(N)] returns th
32b70 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  e number.**     
32b80 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 61 63       of bytes ac
32b90 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68  tually freed, wh
32ba0 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
32bb0 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20  e or less.**    
32bc0 20 20 20 20 20 20 74 68 61 6e 20 74 68 65 20 61        than the a
32bd0 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
32be0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32bf0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
32c00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32c10 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20  3REF:  Impose A 
32c20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
32c30 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a  ze {F17350}.**.*
32c40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f  * The sqlite3_so
32c50 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20  ft_heap_limit() 
32c60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61  interface.** pla
32c70 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  ces a "soft" lim
32c80 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
32c90 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
32ca0 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
32cb0 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69  cated.** by SQLi
32cc0 74 65 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e  te. If an intern
32cd0 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  al allocation is
32ce0 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74   requested .** t
32cf0 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  hat would exceed
32d00 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
32d10 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72  imit, [sqlite3_r
32d20 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
32d30 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f   is.** invoked o
32d40 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
32d50 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65   to free up some
32d60 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68   space before th
32d70 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  e allocation.** 
32d80 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54  is made..**.** T
32d90 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c  he limit is call
32da0 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75  ed "soft", becau
32db0 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  se if.** [sqlite
32dc0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
32dd0 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72  ()] cannot.** fr
32de0 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  ee sufficient me
32df0 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20  mory to prevent 
32e00 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62  the limit from b
32e10 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a  eing exceeded,.*
32e20 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  * the memory is 
32e30 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79  allocated anyway
32e40 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
32e50 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
32e60 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67  eds..**.** A neg
32e70 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
32e80 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20  lue for N means 
32e90 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
32ea0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32eb0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
32ec0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
32ed0 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20  )] will only be 
32ee0 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
32ef0 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ry is exhausted.
32f00 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
32f10 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f  value for the so
32f20 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
32f30 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   zero..**.** SQL
32f40 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74  ite makes a best
32f50 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72   effort to honor
32f60 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
32f70 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75 74 20 69  imit.  .** But i
32f80 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
32f90 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 68 6f 6e  limit cannot hon
32fa0 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20  ored, execution 
32fb0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65  will.** continue
32fc0 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f   without error o
32fd0 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20  r notification. 
32fe0 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65   This is why the
32ff0 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61   limit is .** ca
33000 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
33010 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
33020 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
33030 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
33040 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
33050 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
33060 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
33070 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
33080 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
33090 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
330a0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
330b0 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
330c0 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
330d0 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
330e0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
330f0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
33100 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
33110 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
33120 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63  . The value spec
33130 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
33140 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
33150 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75   is an upper bou
33160 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20  nd on the total 
33170 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
33180 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64  n for all thread
33190 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  s. In.** version
331a0 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
331b0 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
331c0 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
331d0 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
331e0 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
331f0 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ds..**.** INVARI
33200 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
33210 33 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  351} The [sqlite
33220 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
33230 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(N)] interface 
33240 70 6c 61 63 65 73 20 61 20 73 6f 66 74 20 6c 69  places a soft li
33250 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mit.**          
33260 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e 20 74 68  of N bytes on th
33270 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
33280 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
33290 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a   be allocated.**
332a0 20 20 20 20 20 20 20 20 20 20 75 73 69 6e 67 20            using 
332b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
332c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
332d0 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61 6e 79  ealloc()] at any
332e0 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20   point.**       
332f0 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a     in time..**.*
33300 2a 20 7b 46 31 36 33 35 32 7d 20 49 66 20 61 20  * {F16352} If a 
33310 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33320 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
33330 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
33340 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 20  ] would.**      
33350 20 20 20 20 63 61 75 73 65 20 74 68 65 20 74 6f      cause the to
33360 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 61 6c  tal amount of al
33370 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 20 74  located memory t
33380 6f 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  o exceed the.** 
33390 20 20 20 20 20 20 20 20 20 73 6f 66 74 20 68 65           soft he
333a0 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e 20 5b  ap limit, then [
333b0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
333c0 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76  memory()] is inv
333d0 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oked.**         
333e0 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74   in an attempt t
333f0 6f 20 72 65 64 75 63 65 20 74 68 65 20 6d 65 6d  o reduce the mem
33400 6f 72 79 20 75 73 61 67 65 20 70 72 69 6f 72 20  ory usage prior 
33410 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a 2a 2a  to proceeding.**
33420 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
33430 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
33440 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2a  tion attempt..**
33450 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 43 61 6c  .** {F16353} Cal
33460 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ls to [sqlite3_m
33470 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
33480 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
33490 74 68 61 74 20 74 72 69 67 67 65 72 0a 2a 2a 20  that trigger.** 
334a0 20 20 20 20 20 20 20 20 20 61 74 74 65 6d 70 74           attempt
334b0 73 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f  s to reduce memo
334c0 72 79 20 75 73 61 67 65 20 74 68 72 6f 75 67 68  ry usage through
334d0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
334e0 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  imit.**         
334f0 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e 74 69   mechanism conti
33500 6e 75 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  nue even if the 
33510 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63  attempt to reduc
33520 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
33530 20 20 20 20 20 75 73 61 67 65 20 69 73 20 75 6e       usage is un
33540 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a  successful..**.*
33550 2a 20 7b 46 31 36 33 35 34 7d 20 41 20 6e 65 67  * {F16354} A neg
33560 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
33570 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 61 20 63  lue for N in a c
33580 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  all to.**       
33590 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74     [sqlite3_soft
335a0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20  _heap_limit(N)] 
335b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
335c0 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20   is no soft.**  
335d0 20 20 20 20 20 20 20 20 68 65 61 70 20 6c 69 6d          heap lim
335e0 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  it and [sqlite3_
335f0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
33600 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a  ] will only be.*
33610 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65  *          calle
33620 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
33630 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78 68 61   completely exha
33640 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  usted..**.** {F1
33650 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 75 6c  6355} The defaul
33660 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
33670 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
33680 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  is zero..**.** {
33690 46 31 36 33 35 38 7d 20 45 61 63 68 20 63 61 6c  F16358} Each cal
336a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 6f  l to [sqlite3_so
336b0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29  ft_heap_limit(N)
336c0 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  ] overrides the.
336d0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
336e0 65 73 20 73 65 74 20 62 79 20 61 6c 6c 20 70 72  es set by all pr
336f0 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f  ior calls..*/.vo
33700 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
33710 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
33720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33730 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  :  Extract Metad
33740 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
33750 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 46  mn Of A Table {F
33760 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12850}.**.** Thi
33770 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74  s routine.** ret
33780 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61  urns meta-data a
33790 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
337a0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
337b0 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a  ific database.**
337c0 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
337d0 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  e using the conn
337e0 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61  ection handle pa
337f0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
33800 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61  t function .** a
33810 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
33820 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
33830 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
33840 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
33850 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
33860 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66  rs to .** this f
33870 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63  unction. The sec
33880 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
33890 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
338a0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
338b0 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
338c0 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61  , "temp" or an a
338d0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
338e0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
338f0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
33900 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20  ble or NULL. If 
33910 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
33920 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
33930 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
33940 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
33950 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
33960 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61  same algorithm a
33970 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
33980 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a  ngine uses to .*
33990 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
339a0 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
339b0 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rences..**.** Th
339c0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
339d0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
339e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
339f0 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
33a00 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65   column .** name
33a10 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
33a20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
33a30 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
33a40 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
33a50 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  s .** may be NUL
33a60 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e  L..**.** Meta in
33a70 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74  formation is ret
33a80 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
33a90 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
33aa0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
33ab0 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e  as.** the 5th an
33ac0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
33ad0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
33ae0 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66  function. Any of
33af0 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d   these .** argum
33b00 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c  ents may be NULL
33b10 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
33b20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
33b30 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
33b40 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  a .** informatio
33b50 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a  n is ommitted..*
33b60 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61  *.** <pre>.** Pa
33b70 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70  rameter     Outp
33b80 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73  ut Type      Des
33b90 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d  cription.** ----
33ba0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
33bb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
33bc0 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20  **.**   5th     
33bd0 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
33be0 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a       Data type.*
33bf0 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20  *   6th         
33c00 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20  const char*     
33c10 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Name of the def
33c20 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
33c30 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74  equence .**   7t
33c40 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
33c50 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
33c60 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61  if the column ha
33c70 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
33c80 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68  straint.**   8th
33c90 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
33ca0 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
33cb0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
33cc0 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
33cd0 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68  ARY KEY.**   9th
33ce0 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
33cf0 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
33d00 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
33d10 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a  AUTOINCREMENT.**
33d20 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a   </pre>.**.**.**
33d30 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e   The memory poin
33d40 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
33d50 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
33d60 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
33d70 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  e .** declaratio
33d80 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
33d90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
33da0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
33db0 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63  l the next .** c
33dc0 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74  all to any sqlit
33dd0 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
33de0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
33df0 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
33e00 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
33e10 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69   then an error i
33e20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
33e30 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
33e40 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
33e50 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
33e60 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20  _rowid_" and an 
33e70 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d  .** INTEGER PRIM
33e80 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68  ARY KEY column h
33e90 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
33ea0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
33eb0 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a  n the output .**
33ec0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
33ed0 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
33ee0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
33ef0 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65  column. If there
33f00 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
33f10 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50  itly declared IP
33f20 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  K column, then t
33f30 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65  he output parame
33f40 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20  ters are set as 
33f50 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a  .** follows:.**.
33f60 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
33f70 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
33f80 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
33f90 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
33fa0 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
33fb0 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
33fc0 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
33fd0 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
33fe0 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
33ff0 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  pre>.**.** This 
34000 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
34010 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
34020 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
34030 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
34040 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
34050 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
34060 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
34070 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
34080 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
34090 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
340a0 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f   SQLITE error co
340b0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  de is returned a
340c0 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
340d0 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74  age.** left in t
340e0 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
340f0 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  le (to be retrie
34100 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
34110 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
34120 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
34130 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
34140 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
34150 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
34160 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  he.** SQLITE_ENA
34170 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
34180 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
34190 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
341a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
341b0 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
341c0 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
341d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
341e0 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
341f0 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
34200 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
34210 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
34220 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
34230 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
34240 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
34250 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
34260 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
34270 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
34280 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
34290 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
342a0 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
342b0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
342c0 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
342d0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
342e0 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
342f0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
34300 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34310 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
34320 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
34330 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
34340 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
34350 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
34360 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
34370 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
34380 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
34390 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
343a0 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
343b0 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
343c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
343d0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
343e0 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
343f0 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
34400 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
34410 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
34420 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12600}.**.** 
34430 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c  {F12601} The sql
34440 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
34450 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ion() interface.
34460 2a 2a 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c  ** attempts to l
34470 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78  oad an SQLite ex
34480 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
34490 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
344a0 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20   file.** zFile. 
344b0 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74  {F12602} The ent
344c0 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
344d0 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a 50 72 6f  c. {F12603} zPro
344e0 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a 20 69 6e  c may be 0.** in
344f0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
34500 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
34510 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c 74 73  y point defaults
34520 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  .** to "sqlite3_
34530 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
34540 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 34 7d 20  .**.** {F12604} 
34550 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
34560 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
34570 65 72 66 61 63 65 20 73 68 61 6c 6c 0a 2a 2a 20  erface shall.** 
34580 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
34590 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
345a0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
345b0 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
345c0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20  es wrong..**.** 
345d0 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49 66 20 61  {F12605}.** If a
345e0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
345f0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
34600 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
34610 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  * sqlite3_load_e
34620 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
34630 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d  face shall attem
34640 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70 7a 45 72  pt to fill *pzEr
34650 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72  rMsg with .** er
34660 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
34670 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
34680 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34690 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
346a0 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20 20 54 68  )]..** {END}  Th
346b0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
346c0 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74  on should free t
346d0 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79  his memory.** by
346e0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
346f0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
34700 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20 45 78 74   {F12606}.** Ext
34710 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
34720 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
34730 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
34740 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
34750 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ion()].** prior 
34760 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
34770 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  API or an error 
34780 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
34790 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
347a0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
347b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
347c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
347d0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
347e0 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
347f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
34800 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
34810 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
34820 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
34830 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
34840 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
34850 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
34860 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
34870 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
34880 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
34890 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
348a0 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
348b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
348c0 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
348d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
348e0 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44  EF:  Enable Or D
348f0 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  isable Extension
34900 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 32 30   Loading {F12620
34910 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f  }.**.** So as no
34920 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
34930 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
34940 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
34950 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
34960 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
34970 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
34980 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
34990 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
349a0 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
349b0 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
349c0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
349d0 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
349e0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69  llowing.** API i
349f0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
34a00 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
34a10 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
34a20 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
34a30 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b 46 31 32  nd.** off.  {F12
34a40 36 32 32 7d 20 49 74 20 69 73 20 6f 66 66 20 62  622} It is off b
34a50 79 20 64 65 66 61 75 6c 74 2e 20 7b 45 4e 44 7d  y default. {END}
34a60 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
34a70 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 32 31  3..**.** {F12621
34a80 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74  } Call the sqlit
34a90 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
34aa0 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
34ab0 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e 6f 66 66  ne.** with onoff
34ac0 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65 78 74 65  ==1 to turn exte
34ad0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e  nsion loading on
34ae0 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69 74 20  .** and call it 
34af0 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f  with onoff==0 to
34b00 20 74 75 72 6e 20 69 74 20 62 61 63 6b 20 6f 66   turn it back of
34b10 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44 7d 0a 2a  f again. {END}.*
34b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
34b30 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
34b40 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
34b50 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
34b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
34b70 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20  ke Arrangements 
34b80 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  To Automatically
34b90 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
34ba0 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a 2a 0a 2a  on {F12640}.**.*
34bb0 2a 20 7b 46 31 32 36 34 31 7d 20 54 68 69 73 20  * {F12641} This 
34bc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 67 69  function.** regi
34bd0 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
34be0 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
34bf0 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  hat is automatic
34c00 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ally invoked.** 
34c10 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 64  whenever a new d
34c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34c30 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69  on is opened usi
34c40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ng.** [sqlite3_o
34c50 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
34c60 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
34c70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
34c80 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  )]. {END}.**.** 
34c90 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20  This API can be 
34ca0 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72  invoked at progr
34cb0 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72  am startup in or
34cc0 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a  der to register.
34cd0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ** one or more s
34ce0 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
34cf0 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74   extensions that
34d00 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62   will be availab
34d10 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77  le.** to all new
34d20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34d30 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tions..**.** {F1
34d40 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20  2642} Duplicate 
34d50 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64  extensions are d
34d60 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69  etected so calli
34d70 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
34d80 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
34d90 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
34da0 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72  extension is har
34db0 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  mless..**.** {F1
34dc0 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69  2643} This routi
34dd0 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e  ne stores a poin
34de0 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e  ter to the exten
34df0 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79  sion in an array
34e00 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62 74 61  .** that is obta
34e10 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
34e20 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45 4e 44 7d  _malloc(). {END}
34e30 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65   If you run a me
34e40 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65  mory leak.** che
34e50 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f  cker on your pro
34e60 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f  gram and it repo
34e70 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75  rts a leak becau
34e80 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72  se of this.** ar
34e90 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  ray, then invoke
34ea0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
34eb0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
34ec0 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68  ] prior.** to sh
34ed0 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74  utdown to free t
34ee0 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a  he memory..**.**
34ef0 20 7b 46 31 32 36 34 34 7d 20 41 75 74 6f 6d 61   {F12644} Automa
34f00 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  tic extensions a
34f10 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  pply across all 
34f20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a  threads. {END}.*
34f30 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
34f40 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ace is experimen
34f50 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
34f60 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a  ct to change or.
34f70 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  ** removal in fu
34f80 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
34f90 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
34fa0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
34fb0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e  ension(void *xEn
34fc0 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a  tryPoint);.../*.
34fd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
34fe0 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74  et Automatic Ext
34ff0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
35000 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12660}.**.** {F
35010 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63  12661} This func
35020 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c  tion disables al
35030 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  l previously reg
35040 69 73 74 65 72 65 64 0a 2a 2a 20 61 75 74 6f 6d  istered.** autom
35050 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e  atic extensions.
35060 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a 2a 2a 20   {END}  This.** 
35070 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
35080 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
35090 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f   prior [sqlite3_
350a0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
350b0 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  ].** calls..**.*
350c0 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69 73 20  * {F12662} This 
350d0 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75  call disabled au
350e0 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
350f0 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
35100 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  s. {END}.**.** T
35110 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
35120 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
35130 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
35140 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
35150 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
35160 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
35170 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
35180 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
35190 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
351a0 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  ./*.****** EXPER
351b0 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
351c0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
351d0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
351e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20  *********.**.** 
351f0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
35200 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
35210 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
35220 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
35230 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
35240 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
35250 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
35260 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
35270 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
35280 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
35290 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
352a0 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
352b0 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
352c0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
352d0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
352e0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
352f0 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  blizes, we will 
35300 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
35310 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
35320 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
35330 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
35340 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
35350 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
35360 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
35370 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
35380 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
35390 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
353a0 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
353b0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
353c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
353d0 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
353e0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
353f0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
35400 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
35410 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
35420 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
35430 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
35440 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
35450 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
35460 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
35470 6c 65 20 4f 62 6a 65 63 74 20 7b 46 31 38 30 30  le Object {F1800
35480 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
35490 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a  sqlite3_module.*
354a0 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73  *.** A module is
354b0 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74   a class of virt
354c0 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63  ual tables.  Eac
354d0 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69  h module is defi
354e0 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73  ned.** by an ins
354f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c  tance of the fol
35500 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
35510 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72  .  This structur
35520 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f  e consists.** mo
35530 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
35540 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
35550 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
35560 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
35570 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
35580 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
35590 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
355a0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
355b0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
355c0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
355d0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
355e0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
355f0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
35600 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
35610 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
35620 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
35630 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
35640 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
35650 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
35660 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
35670 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
35680 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
35690 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
356a0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
356b0 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
356c0 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
356d0 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
356e0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
356f0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
35700 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
35710 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
35720 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
35730 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
35740 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35750 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
35760 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
35770 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
35780 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
35790 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
357a0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
357b0 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
357c0 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
357d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
357e0 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
357f0 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
35800 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
35810 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
35820 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
35830 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
35840 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
35850 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
35860 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
35870 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
35880 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
35890 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
358a0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
358b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
358c0 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
358d0 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
358e0 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
358f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
35900 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
35910 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
35920 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35930 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35940 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
35950 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
35960 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
35970 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35980 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
35990 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
359a0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
359b0 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
359c0 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
359d0 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
359e0 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
359f0 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
35a00 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
35a10 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
35a20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35a30 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35a40 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
35a50 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
35a60 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74  **ppArg);..  int
35a70 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
35a80 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
35a90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
35aa0 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  w);.};../*.** CA
35ab0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
35ac0 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49  Table Indexing I
35ad0 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46 31 38 31  nformation {F181
35ae0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
35af0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
35b00 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nfo.**.** The sq
35b10 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
35b20 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
35b30 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
35b40 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70   is used to.** p
35b50 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
35b60 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
35b70 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
35b80 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 0a 2a  the xBestIndex.*
35b90 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 73  * method of an s
35ba0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20  qlite3_module.  
35bb0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
35bc0 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
35bd0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
35be0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
35bf0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
35c00 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
35c10 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
35c20 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
35c30 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
35c40 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  *.** The aConstr
35c50 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63  aint[] array rec
35c60 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73  ords WHERE claus
35c70 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66  e constraints of
35c80 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a   the.** form:.**
35c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 6f 6c 75  .**         colu
35ca0 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a  mn OP expr.**.**
35cb0 20 57 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   Where OP is =, 
35cc0 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
35cd0 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 0a 2a  ;, or &gt;=.  .*
35ce0 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72  * The particular
35cf0 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73 74 6f   operator is sto
35d00 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73 74  red.** in aConst
35d10 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65  raint[].op.  The
35d20 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
35d30 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
35d40 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  n .** aConstrain
35d50 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43  t[].iColumn.  aC
35d60 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
35d70 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
35d80 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
35d90 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
35da0 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
35db0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
35dc0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
35dd0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
35de0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
35df0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d  .**.** The optim
35e00 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
35e10 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
35e20 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
35e30 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
35e40 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
35e50 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
35e60 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
35e70 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
35e80 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
35e90 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
35ea0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
35eb0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
35ec0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
35ed0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
35ee0 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
35ef0 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
35f00 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65  use terms in the
35f10 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d   correct.** form
35f20 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74   that refer to t
35f30 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69  he particular vi
35f40 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e  rtual table bein
35f50 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a  g queried..**.**
35f60 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   Information abo
35f70 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
35f80 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
35f90 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
35fa0 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20  ** Each term of 
35fb0 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
35fc0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
35fd0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35fe0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73  ..**.** The xBes
35ff0 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75  tIndex method mu
36000 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
36010 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
36020 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
36030 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
36040 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
36050 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67  xFilter.  If arg
36060 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
36070 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
36080 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
36090 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
360a0 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
360b0 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
360c0 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
360d0 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
360e0 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61  gv.  If aConstra
360f0 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
36100 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
36110 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
36120 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
36130 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
36140 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
36150 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
36160 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
36170 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
36180 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20   The idxNum and 
36190 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
361a0 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
361b0 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74  assed into xFilt
361c0 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  er..** sqlite3_f
361d0 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74 6f  ree() is used to
361e0 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
361f0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
36200 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
36210 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
36220 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
36230 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74  utput from xFilt
36240 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  er will occur in
36250 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
36260 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
36270 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
36280 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
36290 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
362a0 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
362b0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
362c0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61  estimatedCost va
362d0 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61  lue is an estima
362e0 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f  te of the cost o
362f0 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70  f doing the.** p
36300 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70  articular lookup
36310 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f  .  A full scan o
36320 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e  f a table with N
36330 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
36340 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f  have.** a cost o
36350 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73  f N.  A binary s
36360 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65  earch of a table
36370 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68   of N entries sh
36380 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63  ould have a.** c
36390 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61  ost of approxima
363a0 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a  tely log(N)..*/.
363b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
363c0 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a  ndex_info {.  /*
363d0 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74   Inputs */.  int
363e0 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20   nConstraint;   
363f0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
36400 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20  r of entries in 
36410 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20  aConstraint */. 
36420 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
36430 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
36440 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
36450 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
36460 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c    /* Column on l
36470 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
36480 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
36490 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
364a0 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a  r op;         /*
364b0 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72   Constraint oper
364c0 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  ator */.     uns
364d0 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c  igned char usabl
364e0 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69  e;     /* True i
364f0 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  f this constrain
36500 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20  t is usable */. 
36510 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66      int iTermOff
36520 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  set;          /*
36530 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
36540 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68   - xBestIndex sh
36550 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20  ould ignore */. 
36560 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b   } *aConstraint;
36570 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
36580 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c  able of WHERE cl
36590 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
365a0 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72   */.  int nOrder
365b0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
365c0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65   /* Number of te
365d0 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52  rms in the ORDER
365e0 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
365f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
36600 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20  ndex_orderby {. 
36610 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
36620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36630 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a   Column number *
36640 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
36650 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20  char desc;      
36660 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53   /* True for DES
36670 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53  C.  False for AS
36680 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65  C. */.  } *aOrde
36690 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20  rBy;            
366a0 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20     /* The ORDER 
366b0 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20  BY clause */..  
366c0 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20  /* Outputs */.  
366d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
366e0 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f  ndex_constraint_
366f0 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20  usage {.    int 
36700 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
36710 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63       /* if >0, c
36720 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72  onstraint is par
36730 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69  t of argv to xFi
36740 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69  lter */.    unsi
36750 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
36760 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
36770 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
36780 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
36790 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
367a0 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69  ntUsage;.  int i
367b0 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20  dxNum;          
367c0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
367d0 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79  used to identify
367e0 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20   the index */.  
367f0 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20  char *idxStr;   
36800 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
36810 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f  ring, possibly o
36820 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
36830 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20  ite3_malloc */. 
36840 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49   int needToFreeI
36850 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46  dxStr;      /* F
36860 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67  ree idxStr using
36870 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
36880 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74  if true */.  int
36890 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
368a0 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
368b0 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72  if output is alr
368c0 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a  eady ordered */.
368d0 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74    double estimat
368e0 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20  edCost;      /* 
368f0 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f  Estimated cost o
36900 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64  f using this ind
36910 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65  ex */.};.#define
36920 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
36930 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32  NSTRAINT_EQ    2
36940 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36950 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
36960 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65  _GT    4.#define
36970 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
36980 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38  NSTRAINT_LE    8
36990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
369a0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
369b0 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e  _LT    16.#defin
369c0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
369d0 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20  ONSTRAINT_GE    
369e0 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
369f0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
36a00 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a  NT_MATCH 64../*.
36a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
36a20 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
36a30 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
36a40 74 69 6f 6e 20 7b 46 31 38 32 30 30 7d 0a 2a 2a  tion {F18200}.**
36a50 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
36a60 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 69   is used to regi
36a70 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64 75 6c  ster a new modul
36a80 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e 20 53  e name with an S
36a90 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  QLite.** connect
36aa0 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e 61 6d  ion.  Module nam
36ab0 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73  es must be regis
36ac0 74 65 72 65 64 20 62 65 66 6f 72 65 20 63 72 65  tered before cre
36ad0 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76 69 72  ating new.** vir
36ae0 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e 20 74  tual tables on t
36af0 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65  he module, or be
36b00 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65 65 78  fore using preex
36b10 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c 0a 2a  isting virtual.*
36b20 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68 65 20  * tables of the 
36b30 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73  module..*/.int s
36b40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
36b50 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  dule(.  sqlite3 
36b60 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36b70 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
36b80 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
36b90 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
36ba0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36bb0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
36bc0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
36bd0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
36be0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
36bf0 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *,    /* Methods
36c00 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
36c10 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20 20 20  */.  void *     
36c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c30 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
36c40 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
36c50 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ect */.);../*.**
36c60 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
36c70 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
36c80 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
36c90 6f 6e 20 7b 46 31 38 32 31 30 7d 0a 2a 2a 0a 2a  on {F18210}.**.*
36ca0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
36cb0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74  s identical to t
36cc0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
36cd0 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68 6f  e_module() metho
36ce0 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65  d above,.** exce
36cf0 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77  pt that it allow
36d00 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
36d10 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70  unction to be sp
36d20 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a  ecified. It is.*
36d30 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65  * even more expe
36d40 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68  rimental than th
36d50 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76 69  e rest of the vi
36d60 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49  rtual tables API
36d70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36d80 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
36d90 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
36da0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36db0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
36dc0 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
36dd0 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
36de0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
36df0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
36e00 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
36e10 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
36e20 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20  lite3_module *, 
36e30 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
36e40 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
36e50 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
36e60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36e70 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
36e80 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
36e90 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73   */.  void(*xDes
36ea0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20  troy)(void*)    
36eb0 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72   /* Module destr
36ec0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a  uctor function *
36ed0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
36ee0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
36ef0 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a  ble Instance Obj
36f00 65 63 74 20 7b 46 31 38 30 31 30 7d 0a 2a 2a 20  ect {F18010}.** 
36f10 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
36f20 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65  3_vtab.**.** Eve
36f30 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
36f40 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
36f50 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
36f60 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
36f70 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
36f80 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  be a particular 
36f90 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
36fa0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75  module.  Each su
36fb0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
36fc0 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
36fd0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
36fe0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
36ff0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
37000 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20   The.** purpose 
37010 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
37020 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
37030 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
37040 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a  hat are common.*
37050 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  * to all module 
37060 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
37070 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
37080 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
37090 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
370a0 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
370b0 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
370c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
370d0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
370e0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
370f0 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
37100 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
37110 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
37120 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
37130 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
37140 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20  free().** prior 
37150 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
37160 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
37170 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65  rMsg.  After the
37180 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
37190 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
371a0 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
371b0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
371c0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
371d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
371e0 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
371f0 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
37200 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
37210 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20  ill be zeroed.  
37220 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c  Note.** that sql
37230 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
37240 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  nd sqlite3_free(
37250 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68  ) are used on th
37260 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a  e zErrMsg field.
37270 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c  ** since virtual
37280 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d   tables are comm
37290 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64  only implemented
372a0 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74   in loadable ext
372b0 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a  ensions which.**
372c0 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63   do not have acc
372d0 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50  ess to sqlite3MP
372e0 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74  rintf() or sqlit
372f0 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72  e3Free()..*/.str
37300 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
37310 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74   {.  const sqlit
37320 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
37330 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75  le;  /* The modu
37340 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74  le for this virt
37350 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69  ual table */.  i
37360 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20  nt nRef;        
37370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
37380 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
37390 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  y */.  char *zEr
373a0 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
373b0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
373c0 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
373d0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
373e0 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
373f0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
37400 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
37410 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
37420 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
37430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37440 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43   Virtual Table C
37450 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 46  ursor Object  {F
37460 31 38 30 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  18020}.** KEYWOR
37470 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
37480 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a 2a 20 45 76  _cursor.**.** Ev
37490 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
374a0 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
374b0 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
374c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
374d0 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
374e0 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
374f0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
37500 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
37510 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
37520 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
37530 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
37540 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
37550 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
37560 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
37570 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
37580 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
37590 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
375a0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
375b0 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
375c0 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
375d0 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
375e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
375f0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
37600 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
37610 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
37620 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
37630 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
37640 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
37650 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  s..*/.struct sql
37660 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
37670 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61   {.  sqlite3_vta
37680 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f  b *pVtab;      /
37690 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
376a0 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a  of this cursor *
376b0 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
376c0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
376d0 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
376e0 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
376f0 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
37700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37710 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68   Declare The Sch
37720 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c  ema Of A Virtual
37730 20 54 61 62 6c 65 20 7b 46 31 38 32 38 30 7d 0a   Table {F18280}.
37740 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74  **.** The xCreat
37750 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d  e and xConnect m
37760 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75  ethods of a modu
37770 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f  le use the follo
37780 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64  wing API.** to d
37790 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
377a0 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
377b0 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
377c0 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
377d0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
377e0 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
377f0 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
37800 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
37810 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
37820 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62  char *zCreateTab
37830 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  le);../*.** CAPI
37840 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
37850 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
37860 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 46  Virtual Table {F
37870 31 38 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 56 69 72  18300}.**.** Vir
37880 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
37890 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
378a0 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
378b0 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
378c0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46  .** using the xF
378d0 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68  indFunction meth
378e0 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20  od.  But global 
378f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
37900 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
37910 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
37920 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
37930 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ded..**.** This 
37940 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
37950 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
37960 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
37970 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
37980 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
37990 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
379a0 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
379b0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
379c0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
379d0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
379e0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
379f0 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  n is created.  T
37a00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
37a10 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
37a20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
37a30 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
37a40 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
37a50 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
37a60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
37a70 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
37a80 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
37a90 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
37aa0 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
37ab0 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74  ace-holder funct
37ac0 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20  ion that can be 
37ad0 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79  overloaded.** by
37ae0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
37af0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
37b00 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64  should be consid
37b10 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65  ered part of the
37b20 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
37b30 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69  nterface,.** whi
37b40 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ch is experiment
37b50 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74  al and subject t
37b60 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  o change..*/.int
37b70 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
37b80 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
37b90 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
37ba0 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
37bb0 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
37bc0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
37bd0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
37be0 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
37bf0 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
37c00 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
37c10 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
37c20 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
37c30 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
37c40 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
37c50 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
37c60 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
37c70 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
37c80 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
37c90 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
37ca0 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
37cb0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
37cc0 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
37cd0 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
37ce0 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
37cf0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
37d00 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
37d10 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
37d20 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
37d30 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
37d40 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
37d50 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
37d60 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  omment..**.*****
37d70 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d  * EXPERIMENTAL -
37d80 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
37d90 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ge without notic
37da0 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e **************
37db0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
37dc0 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
37dd0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46   An Open BLOB {F
37de0 31 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  17800}.**.** An 
37df0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
37e00 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
37e10 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
37e20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 69 6e 63 72  on which.** incr
37e30 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 63 61 6e 20  emental I/O can 
37e40 62 65 20 70 72 65 66 6f 72 6d 65 64 2e 0a 2a 2a  be preformed..**
37e50 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73   Objects of this
37e60 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65   type are create
37e70 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
37e80 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
37e90 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  d destroyed by [
37ea0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
37eb0 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  se()]..** The [s
37ec0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
37ed0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
37ee0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69  _blob_write()] i
37ef0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e  nterfaces.** can
37f00 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64   be used to read
37f10 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20   or write small 
37f20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74  subsections of t
37f30 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20  he blob..** The 
37f40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
37f50 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
37f60 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
37f70 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f 62  e of the.** blob
37f80 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
37f90 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
37fa0 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
37fb0 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
37fc0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
37fd0 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
37fe0 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37 38 31 30  ntal I/O {F17810
37ff0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
38000 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20  erfaces opens a 
38010 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c  handle to the bl
38020 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e  ob located.** in
38030 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d   row iRow, colum
38040 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65  n zColumn, table
38050 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62   zTable in datab
38060 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f  ase zDb;.** in o
38070 74 68 65 72 20 77 6f 72 64 73 2c 20 20 74 68 65  ther words,  the
38080 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 74 20   same blob that 
38090 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65  would be selecte
380a0 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  d by:.**.** <pre
380b0 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20  >.**     SELECT 
380c0 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62  zColumn FROM zDb
380d0 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f  .zTable WHERE ro
380e0 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  wid = iRow;.** <
380f0 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  /pre> {END}.**.*
38100 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70  * If the flags p
38110 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
38120 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69  zero, the blob i
38130 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a  s opened for .**
38140 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20   read and write 
38150 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73  access. If it is
38160 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20   zero, the blob 
38170 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
38180 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a  ad .** access..*
38190 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
381a0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
381b0 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   is not the file
381c0 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69  name that contai
381d0 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
381e0 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68  se but rather th
381f0 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
38200 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
38210 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67  that.** is assig
38220 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ned when the dat
38230 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74  abase is connect
38240 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48  ed using [ATTACH
38250 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61  ]..** For the ma
38260 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
38270 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
38280 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 20 20  ame is "main".  
38290 46 6f 72 0a 2a 2a 20 54 45 4d 50 20 74 61 62 6c  For.** TEMP tabl
382a0 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
382b0 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
382c0 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
382d0 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
382e0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74  s returned and t
382f0 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69  he new .** [sqli
38300 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20  te3_blob | blob 
38310 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74  handle] is writt
38320 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 0a  en to *ppBlob. .
38330 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  ** Otherwise an 
38340 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
38350 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61  turned and .** a
38360 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e  ny value written
38370 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75   to *ppBlob shou
38380 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
38390 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a  y the caller..**
383a0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   This function s
383b0 65 74 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ets the database
383c0 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f  -handle error co
383d0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a  de and message.*
383e0 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  * accessible via
383f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
38400 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
38410 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
38420 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
38430 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33 7d 20 41  **.** {F17813} A
38440 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
38450 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
38460 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
38470 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d  (D,B,T,C,R,F,P)]
38480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
38490 65 72 66 61 63 65 20 6f 70 65 6e 73 20 61 6e 20  erface opens an 
384a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f  [sqlite3_blob] o
384b0 62 6a 65 63 74 20 50 20 6f 6e 20 74 68 65 20 62  bject P on the b
384c0 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lob.**          
384d0 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f 66 20 74  in column C of t
384e0 61 62 6c 65 20 54 20 69 6e 20 64 61 74 61 62 61  able T in databa
384f0 73 65 20 42 20 6f 6e 20 5b 64 61 74 61 62 61 73  se B on [databas
38500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
38510 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 34 7d 20  .**.** {F17814} 
38520 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
38530 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
38540 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c  te3_blob_open(D,
38550 2e 2e 2e 29 5d 20 73 74 61 72 74 73 0a 2a 2a 20  ...)] starts.** 
38560 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 74           a new t
38570 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 5b 64  ransaction on [d
38580 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38590 6f 6e 5d 20 44 20 69 66 20 74 68 61 74 20 63 6f  on] D if that co
385a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
385b0 20 20 20 20 20 69 73 20 6e 6f 74 20 61 6c 72 65       is not alre
385c0 61 64 79 20 69 6e 20 61 20 74 72 61 6e 73 61 63  ady in a transac
385d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  tion..**.** {F17
385e0 38 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  816} The [sqlite
385f0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c  3_blob_open(D,B,
38600 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e 74 65  T,C,R,F,P)] inte
38610 72 66 61 63 65 20 6f 70 65 6e 73 20 74 68 65 20  rface opens the 
38620 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20 20  blob.**         
38630 20 66 6f 72 20 72 65 61 64 20 61 6e 64 20 77 72   for read and wr
38640 69 74 65 20 61 63 63 65 73 73 20 69 66 20 61 6e  ite access if an
38650 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 46 20  d only if the F 
38660 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
38670 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 7a 65 72        is non-zer
38680 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 39  o..**.** {F17819
38690 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
386a0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 69 6e 74 65  lob_open()] inte
386b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53  rface returns [S
386c0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 0a 2a 2a  QLITE_OK] on .**
386d0 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65 73            succes
386e0 73 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  s and an appropr
386f0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
38700 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  ] on failure..**
38710 0a 2a 2a 20 7b 46 31 37 38 32 31 7d 20 49 66 20  .** {F17821} If 
38720 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
38730 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f  during evaluatio
38740 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c  n of [sqlite3_bl
38750 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 0a  ob_open(D,...)].
38760 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
38770 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
38780 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
38790 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20  rcode(D)],.**   
387a0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
387b0 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20  errmsg(D)], and 
387c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
387d0 36 28 44 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  6(D)] will retur
387e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
387f0 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70  formation approp
38800 72 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72  rate for that er
38810 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ror..*/.int sqli
38820 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20  te3_blob_open(. 
38830 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e   sqlite3*,.  con
38840 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20  st char *zDb,.  
38850 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
38860 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  le,.  const char
38870 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c   *zColumn,.  sql
38880 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c  ite3_int64 iRow,
38890 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20  .  int flags,.  
388a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70  sqlite3_blob **p
388b0 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  pBlob.);../*.** 
388c0 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f 73 65  CAPI3REF:  Close
388d0 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b   A BLOB Handle {
388e0 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c  F17830}.**.** Cl
388f0 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c  ose an open [sql
38900 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
38910 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
38920 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73  Closing a BLOB s
38930 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63  hall cause the c
38940 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
38950 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20  on to commit.** 
38960 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
38970 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20  other BLOBs, no 
38980 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64  pending prepared
38990 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
389a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
389b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69   connection is i
389c0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f